@frontmcp/utils 1.2.1 → 1.3.0

package/env/browser-runtime-context.d.ts

@@ -1,28 +1,60 @@
 /**
  * Runtime context detection and entry availability matching (Browser version).
  *
- * Returns safe defaults for browser environments.
- * The isEntryAvailable matcher works identically to the Node version.
+ * Returns safe defaults for browser environments. The matcher and
+ * `EntryAvailability` shape track the Node version (issue #417 added
+ * `os`/`provider`/`target`/`surface`).
  */
 export interface RuntimeContext {
+    /** Issue #417: renamed from `platform`. */
+    os: string;
+    /** @deprecated Use `os`. */
     platform: string;
     runtime: string;
     deployment: string;
+    /** Issue #417 — deploy provider. Always `'bare'` in browser. */
+    provider: string;
+    /** Issue #417 — build target. Always `'browser'` in browser. */
+    target: string;
     env: string;
 }
+export type Surface = 'mcp' | 'cli' | 'http-trigger' | 'job' | 'agent';
+export interface CallContext {
+    surface?: Surface;
+}
 export interface EntryAvailability {
+    /** Issue #417: renamed from `platform`. */
+    os?: string[];
+    /** @deprecated Use `os`. */
     platform?: string[];
     runtime?: string[];
     deployment?: string[];
+    provider?: string[];
+    target?: string[];
+    surface?: Surface[];
     env?: string[];
 }
 export declare const entryAvailabilitySchema: import("@frontmcp/lazy-zod").ZodObject<{
+    os: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     platform: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     runtime: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     deployment: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    provider: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    target: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    surface: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodEnum<{
+        cli: "cli";
+        mcp: "mcp";
+        "http-trigger": "http-trigger";
+        job: "job";
+        agent: "agent";
+    }>>>;
     env: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
 }, import("zod/v4/core").$strict>;
-export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext): boolean;
+export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext, callCtx?: CallContext): boolean;
+export declare function checkEntryAvailability(availability: EntryAvailability | undefined, ctx: RuntimeContext, callCtx?: CallContext): {
+    available: boolean;
+    missingAxes: (keyof EntryAvailability)[];
+};
 export declare function detectRuntimeContext(): RuntimeContext;
 export declare function getRuntimeContext(): RuntimeContext;
 export declare function resetRuntimeContext(): void;

package/env/build-target.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Build-target detection (issue #417).
+ *
+ * The CLI's `build` command knows the target name (`cli`, `node`,
+ * `vercel`, `lambda`, `cloudflare`, `browser`, `sdk`, `mcpb`,
+ * `distributed`) but doesn't tell the runtime today. This helper exposes
+ * it so `@Tool({ availableWhen: { target: ['cli'] } })` can express
+ * "this tool is only valid in the compiled CLI bundle."
+ *
+ * Resolution order:
+ *
+ *   1. `globalThis.FRONTMCP_BUILD_TARGET` — preferred. Build adapters
+ *      inline `const FRONTMCP_BUILD_TARGET = '<target>';` into the
+ *      emitted entry shim before any user code runs, so this constant
+ *      is correct from the very first line of imports.
+ *   2. `process.env.FRONTMCP_BUILD_TARGET` — set by the build adapter
+ *      via the runtime env when inlining isn't viable (e.g. SEA).
+ *   3. `'unknown'` — dev mode, tests, or any context the build command
+ *      hasn't touched.
+ *
+ * The supported values match `frontmcp build --target <name>` plus
+ * `'unknown'` for the dev path.
+ */
+export type BuildTarget = 'unknown' | 'node' | 'distributed' | 'cli' | 'vercel' | 'lambda' | 'cloudflare' | 'browser' | 'sdk' | 'mcpb';
+export declare function getBuildTarget(): BuildTarget;
+/** Test helper — reset the cache between specs. */
+export declare function resetBuildTargetCacheForTesting(): void;

package/env/index.d.ts

@@ -1,3 +1,7 @@
 export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, } from '#env';
-export { getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, entryAvailabilitySchema, } from '#runtime-context';
-export type { RuntimeContext, EntryAvailability } from '#runtime-context';
+export { getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, checkEntryAvailability, entryAvailabilitySchema, } from '#runtime-context';
+export type { RuntimeContext, EntryAvailability, Surface, CallContext } from '#runtime-context';
+export { detectProvider, resetProviderCacheForTesting } from './provider';
+export type { DeployProvider } from './provider';
+export { getBuildTarget, resetBuildTargetCacheForTesting } from './build-target';
+export type { BuildTarget } from './build-target';

package/env/provider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deploy-provider detection (issue #417).
+ *
+ * `isServerless()` collapses every serverless env to a single boolean;
+ * this returns the discriminated identity so `@Tool({ availableWhen: {
+ * provider: ['vercel'] } })` can express provider-specific rules.
+ *
+ * Order matters — first match wins. A user can override detection by
+ * setting `FRONTMCP_PROVIDER=<name>` explicitly (used by tests and by
+ * Docker images that don't expose a discriminating env var).
+ */
+export type DeployProvider = 'bare' | 'docker' | 'vercel' | 'lambda' | 'cloudflare' | 'netlify' | 'azure' | 'gcp' | 'fly' | 'render' | 'railway';
+/**
+ * Detect the current deploy provider. Cached per process.
+ *
+ * Detection rules (first match wins):
+ *
+ *   1. `FRONTMCP_PROVIDER` env var (override; trust whatever the operator set).
+ *   2. `VERCEL` env var → `'vercel'`.
+ *   3. `AWS_LAMBDA_FUNCTION_NAME` → `'lambda'`.
+ *   4. `CF_PAGES` → `'cloudflare'`.
+ *   5. `NETLIFY` → `'netlify'`.
+ *   6. `AZURE_FUNCTIONS_ENVIRONMENT` → `'azure'`.
+ *   7. `K_SERVICE` (Cloud Run / Knative) → `'gcp'`.
+ *   8. `FLY_APP_NAME` → `'fly'`.
+ *   9. `RENDER` → `'render'`.
+ *  10. `RAILWAY_ENVIRONMENT` → `'railway'`.
+ *  11. `/.dockerenv` exists → `'docker'`.
+ *  12. Fallback: `'bare'`.
+ */
+export declare function detectProvider(): DeployProvider;
+/** Test helper — reset the cache between specs. */
+export declare function resetProviderCacheForTesting(): void;

package/env/runtime-context.d.ts

@@ -2,25 +2,48 @@
  * Runtime context detection and entry availability matching (Node.js version).
  *
  * Provides:
- * - `RuntimeContext` — snapshot of the current platform, runtime, deployment, and env
+ * - `RuntimeContext` — snapshot of the current platform, runtime, deployment, env, provider, target
  * - `EntryAvailability` — declarative constraint for when an entry is available
  * - `getRuntimeContext()` — lazy singleton returning the detected context
  * - `isEntryAvailable()` — pure matcher: does the constraint match the context?
+ * - `checkEntryAvailability()` — structured matcher returning `{available, missingAxes}`
+ *
+ * Issue #417 adds:
+ *   - `os` as the new name for `platform` (alias preserved for back-compat)
+ *   - `provider` (vercel / lambda / cloudflare / netlify / docker / bare / …)
+ *   - `target` (the build output produced by `frontmcp build --target <x>`)
+ *   - `surface` (per-call axis: mcp / cli / agent / job / http-trigger)
  */
 /**
- * Snapshot of the current runtime environment.
- * Detected once and cached for the lifetime of the process.
+ * Snapshot of the current runtime environment. Detected once and cached
+ * for the lifetime of the process.
  */
 export interface RuntimeContext {
-    /** OS platform: 'darwin', 'linux', 'win32', 'freebsd', etc. */
+    /** OS platform: 'darwin', 'linux', 'win32', etc. (issue #417: renamed from platform) */
+    os: string;
+    /** @deprecated Use `os` instead. Legacy alias preserved for back-compat. */
     platform: string;
     /** JavaScript runtime: 'node', 'bun', 'deno', 'edge', 'browser' */
     runtime: string;
     /** Deployment mode: 'distributed', 'serverless', 'standalone', or 'browser' */
     deployment: string;
+    /** Deploy provider (issue #417): 'vercel', 'lambda', 'cloudflare', 'docker', 'bare', … */
+    provider: string;
+    /** Build target produced by `frontmcp build` (issue #417). `'unknown'` in dev. */
+    target: string;
     /** NODE_ENV value: 'production', 'development', 'test', etc. */
     env: string;
 }
+/**
+ * Per-call surface — `surface` is the only axis that varies per request.
+ * Set by transport adapters / agent dispatchers / job runners on the
+ * outgoing `ctx` so registry filtering can fork on call origin.
+ */
+export type Surface = 'mcp' | 'cli' | 'http-trigger' | 'job' | 'agent';
+/** Call-context wrapper threaded through `findTool` for per-call filtering. */
+export interface CallContext {
+    surface?: Surface;
+}
 /**
  * Declarative constraint for entry availability.
  *
@@ -33,21 +56,34 @@ export interface RuntimeContext {
  *
  * @example macOS only
  * ```typescript
- * { platform: ['darwin'] }
+ * { os: ['darwin'] }
+ * ```
+ *
+ * @example CLI binary on Linux only (issue #417)
+ * ```typescript
+ * { target: ['cli'], os: ['linux'] }
  * ```
  *
- * @example Node.js or Bun, production only
+ * @example MCP-only — block CLI / agent / job invocations (issue #417)
  * ```typescript
- * { runtime: ['node', 'bun'], env: ['production'] }
+ * { surface: ['mcp'] }
  * ```
  */
 export interface EntryAvailability {
-    /** OS platform constraint: 'darwin', 'linux', 'win32', etc. */
+    /** OS constraint (issue #417: renamed from `platform`). */
+    os?: string[];
+    /** @deprecated Use `os` instead. Legacy alias preserved for back-compat. */
     platform?: string[];
     /** Runtime constraint: 'node', 'browser', 'edge', 'bun', 'deno' */
     runtime?: string[];
     /** Deployment constraint: 'distributed', 'serverless', 'standalone', 'browser' */
     deployment?: string[];
+    /** Deploy-provider constraint (issue #417). */
+    provider?: string[];
+    /** Build-target constraint (issue #417). */
+    target?: string[];
+    /** Surface constraint (issue #417): 'mcp', 'cli', 'agent', 'job', 'http-trigger'. */
+    surface?: Surface[];
     /** Environment constraint: 'production', 'development', 'test', etc. */
     env?: string[];
 }
@@ -55,19 +91,43 @@ export interface EntryAvailability {
  * Zod schema for validating EntryAvailability in metadata.
  */
 export declare const entryAvailabilitySchema: import("@frontmcp/lazy-zod").ZodObject<{
+    os: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     platform: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     runtime: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     deployment: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    provider: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    target: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
+    surface: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodEnum<{
+        cli: "cli";
+        mcp: "mcp";
+        "http-trigger": "http-trigger";
+        job: "job";
+        agent: "agent";
+    }>>>;
     env: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
 }, import("zod/v4/core").$strict>;
 /**
  * Check if an entry is available in the given runtime context.
  *
+ * Surface is checked separately because it's a per-call axis, not a
+ * process-global one. Pass it via `callCtx.surface` to enforce
+ * `availableWhen.surface` at call time.
+ *
  * @param availability - The constraint (undefined = always available)
  * @param ctx - The current runtime context
+ * @param callCtx - Optional per-call context (surface, …)
  * @returns true if the entry should be available
  */
-export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext): boolean;
+export declare function isEntryAvailable(availability: EntryAvailability | undefined, ctx: RuntimeContext, callCtx?: CallContext): boolean;
+/**
+ * Structured variant of `isEntryAvailable` — returns the list of axes
+ * that failed so flow-level call sites can build a `missingAxes`-shaped
+ * error response (issue #417).
+ */
+export declare function checkEntryAvailability(availability: EntryAvailability | undefined, ctx: RuntimeContext, callCtx?: CallContext): {
+    available: boolean;
+    missingAxes: (keyof EntryAvailability)[];
+};
 /**
  * Detect the current runtime context from the environment.
  */

package/esm/index.mjs

@@ -70,8 +70,8 @@ async function readFile(p, encoding = "utf8") {
   return fsp.readFile(p, encoding);
 }
 function readFileSync(p, encoding = "utf8") {
-  const fs = getFs();
-  return fs.readFileSync(p, encoding);
+  const fs2 = getFs();
+  return fs2.readFileSync(p, encoding);
 }
 async function readFileBuffer(p) {
   const fsp = getFsp();
@@ -143,6 +143,10 @@ async function readdir(p) {
   const fsp = getFsp();
   return fsp.readdir(p);
 }
+function readdirSync(p) {
+  const fs2 = getFs();
+  return fs2.readdirSync(p);
+}
 async function rm(p, options) {
   const fsp = getFsp();
   await fsp.rm(p, options);
@@ -562,9 +566,9 @@ function createSecretData(options) {
 }
 async function getOrCreateSecret(options) {
   const cacheKey = resolveSecretPath(options);
-  const cached2 = secretCache.get(cacheKey);
-  if (cached2) {
-    return cached2;
+  const cached4 = secretCache.get(cacheKey);
+  if (cached4) {
+    return cached4;
   }
   const existing = generationPromises.get(cacheKey);
   if (existing) {
@@ -801,8 +805,8 @@ var init_key_persistence = __esm({
        */
       async get(kid) {
         if (this.enableCache) {
-          const cached2 = this.cache.get(kid);
-          if (cached2) return cached2;
+          const cached4 = this.cache.get(kid);
+          if (cached4) return cached4;
         }
         const raw = await this.storage.get(kid);
         if (!raw) return null;
@@ -4185,6 +4189,7 @@ function joinPath(...parts) {
 
 // libs/utils/src/path/node-path.ts
 import { resolve, join, basename, dirname, extname, isAbsolute } from "path";
+import { pathToFileURL } from "url";
 
 // libs/utils/src/content/content.ts
 function sanitizeToJson(value) {
@@ -4483,23 +4488,114 @@ import {
 // libs/utils/src/env/runtime-context.ts
 import { z as z3 } from "@frontmcp/lazy-zod";
 import { isEdgeRuntime, isServerless } from "#env";
+
+// libs/utils/src/env/build-target.ts
+var cached;
+function getBuildTarget() {
+  if (cached) return cached;
+  cached = resolveBuildTarget();
+  return cached;
+}
+function resolveBuildTarget() {
+  const globalAny = globalThis;
+  const fromGlobal = globalAny.FRONTMCP_BUILD_TARGET;
+  if (typeof fromGlobal === "string" && isKnownTarget(fromGlobal)) return fromGlobal;
+  const fromEnv = typeof process !== "undefined" ? process.env?.["FRONTMCP_BUILD_TARGET"] : void 0;
+  if (typeof fromEnv === "string" && isKnownTarget(fromEnv)) return fromEnv;
+  return "unknown";
+}
+function isKnownTarget(value) {
+  return value === "unknown" || value === "node" || value === "distributed" || value === "cli" || value === "vercel" || value === "lambda" || value === "cloudflare" || value === "browser" || value === "sdk" || value === "mcpb";
+}
+
+// libs/utils/src/env/provider.ts
+import * as fs from "node:fs";
+var cached2;
+function detectProvider() {
+  if (cached2) return cached2;
+  cached2 = detectProviderUncached();
+  return cached2;
+}
+function detectProviderUncached() {
+  const explicit = process.env["FRONTMCP_PROVIDER"];
+  if (explicit && isKnownProvider(explicit)) return explicit;
+  if (process.env["VERCEL"]) return "vercel";
+  if (process.env["AWS_LAMBDA_FUNCTION_NAME"]) return "lambda";
+  if (process.env["CF_PAGES"]) return "cloudflare";
+  if (process.env["NETLIFY"]) return "netlify";
+  if (process.env["AZURE_FUNCTIONS_ENVIRONMENT"]) return "azure";
+  if (process.env["K_SERVICE"]) return "gcp";
+  if (process.env["FLY_APP_NAME"]) return "fly";
+  if (process.env["RENDER"]) return "render";
+  if (process.env["RAILWAY_ENVIRONMENT"]) return "railway";
+  try {
+    if (fs.existsSync("/.dockerenv")) return "docker";
+  } catch {
+  }
+  return "bare";
+}
+function isKnownProvider(value) {
+  return value === "bare" || value === "docker" || value === "vercel" || value === "lambda" || value === "cloudflare" || value === "netlify" || value === "azure" || value === "gcp" || value === "fly" || value === "render" || value === "railway";
+}
+
+// libs/utils/src/env/runtime-context.ts
 var entryAvailabilitySchema = z3.object({
+  os: z3.array(z3.string().min(1)).optional(),
   platform: z3.array(z3.string().min(1)).optional(),
   runtime: z3.array(z3.string().min(1)).optional(),
   deployment: z3.array(z3.string().min(1)).optional(),
+  provider: z3.array(z3.string().min(1)).optional(),
+  target: z3.array(z3.string().min(1)).optional(),
+  surface: z3.array(z3.enum(["mcp", "cli", "http-trigger", "job", "agent"])).optional(),
   env: z3.array(z3.string().min(1)).optional()
 }).strict();
-function isEntryAvailable(availability, ctx) {
+var PROCESS_AXES = [
+  // `os` and `platform` both compare against the same RuntimeContext value
+  // — keeping `platform` as a deprecated alias lets pre-#417 metadata
+  // continue to match without any code change.
+  { key: "os", ctxKey: "os" },
+  { key: "platform", ctxKey: "platform" },
+  { key: "runtime", ctxKey: "runtime" },
+  { key: "deployment", ctxKey: "deployment" },
+  { key: "provider", ctxKey: "provider" },
+  { key: "target", ctxKey: "target" },
+  { key: "env", ctxKey: "env" }
+];
+function isEntryAvailable(availability, ctx, callCtx) {
   if (!availability) return true;
-  const fields = ["platform", "runtime", "deployment", "env"];
-  for (const field of fields) {
-    const allowed = availability[field];
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
     if (allowed === void 0) continue;
     if (allowed.length === 0) return false;
-    if (!allowed.includes(ctx[field])) return false;
+    if (!allowed.includes(ctx[ctxKey])) return false;
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) return false;
+    if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) {
+      return false;
+    }
   }
   return true;
 }
+function checkEntryAvailability(availability, ctx, callCtx) {
+  if (!availability) return { available: true, missingAxes: [] };
+  const missing = [];
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0 || !allowed.includes(ctx[ctxKey])) {
+      missing.push(key);
+    }
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) {
+      missing.push("surface");
+    } else if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) {
+      missing.push("surface");
+    }
+  }
+  return { available: missing.length === 0, missingAxes: missing };
+}
 function detectRuntime() {
   if (typeof globalThis !== "undefined" && "Bun" in globalThis) return "bun";
   if (typeof globalThis !== "undefined" && "Deno" in globalThis) return "deno";
@@ -4516,22 +4612,26 @@ function detectDeployment(runtime) {
 }
 function detectRuntimeContext() {
   const runtime = detectRuntime();
+  const os = process.platform;
   return {
-    platform: process.platform,
+    os,
+    platform: os,
     runtime,
     deployment: detectDeployment(runtime),
+    provider: detectProvider(),
+    target: getBuildTarget(),
     env: process.env["NODE_ENV"] || "development"
   };
 }
-var cached;
+var cached3;
 function getRuntimeContext() {
-  if (!cached) {
-    cached = detectRuntimeContext();
+  if (!cached3) {
+    cached3 = detectRuntimeContext();
   }
-  return cached;
+  return cached3;
 }
 function resetRuntimeContext() {
-  cached = void 0;
+  cached3 = void 0;
 }
 
 // libs/utils/src/storage/factory.ts
@@ -5372,8 +5472,8 @@ function loadMachineIdSync() {
   if (!isDevPersistenceEnabled()) return null;
   const machineIdPath = resolveMachineIdPath();
   try {
-    const fs = __require("fs");
-    const content = fs.readFileSync(machineIdPath, "utf8").trim();
+    const fs2 = __require("fs");
+    const content = fs2.readFileSync(machineIdPath, "utf8").trim();
     if (/^[0-9a-f-]{32,36}$/i.test(content)) return content;
     console.warn(`[MachineId] Invalid format at ${machineIdPath}, will regenerate`);
     return null;
@@ -5472,6 +5572,7 @@ export {
   buildPrefix,
   buildSetCookie,
   bytesToHex,
+  checkEntryAvailability,
   clearCachedSecret,
   collapseChar,
   collapseWhitespace,
@@ -5573,6 +5674,7 @@ export {
   parseUriTemplate,
   join as pathJoin,
   resolve as pathResolve,
+  pathToFileURL,
   pemToPublicJwk2 as pemToPublicJwk,
   processPlatformToolCalls,
   randomBytes,
@@ -5582,6 +5684,7 @@ export {
   readFileSync,
   readJSON,
   readdir,
+  readdirSync,
   realpath,
   rename,
   resetRuntimeContext,

package/fs/fs.d.ts

@@ -228,6 +228,21 @@ export declare function cp(src: string, dest: string, options?: {
  * const files = await readdir('/path/to/dir');
  */
 export declare function readdir(p: string): Promise<string[]>;
+/**
+ * List directory contents synchronously.
+ *
+ * **Node.js only** - throws an error if called in browser.
+ *
+ * Use this only when async operations are not possible (e.g., per-scrape
+ * synchronous metrics collectors). Prefer the async `readdir` in most cases.
+ *
+ * @param p - Path to directory
+ * @returns Array of file/directory names
+ *
+ * @example
+ * const files = readdirSync('/proc/self/fd');
+ */
+export declare function readdirSync(p: string): string[];
 /**
  * Remove a file or directory recursively.
  *
@@ -296,4 +311,5 @@ export declare function access(p: string, mode?: number): Promise<void>;
  */
 export declare function runCmd(cmd: string, args: string[], opts?: {
     cwd?: string;
+    env?: NodeJS.ProcessEnv;
 }): Promise<void>;

package/fs/index.d.ts

@@ -1 +1 @@
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';

package/index.d.ts

@@ -9,18 +9,18 @@ export { splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } fro
 export type { NameCase } from './naming';
 export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri';
 export type { ParsedUriTemplate } from './uri';
-export { trimSlashes, joinPath, pathResolve, pathJoin, basename, dirname, extname, isAbsolute } from './path';
+export { trimSlashes, joinPath, pathResolve, pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL, } from './path';
 export { sanitizeToJson, inferMimeType, findNonFiniteNumber } from './content';
 export { validateBaseUrl, buildSetCookie, parseCookies, getCookie, isLocalhost, isSecureRequest } from './http';
 export type { CookieOptions, SecureDetectionRequest } from './http';
-export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
+export { readFile, readFileSync, readFileBuffer, writeFile, mkdir, rename, unlink, stat, copyFile, cp, readdir, readdirSync, realpath, rm, mkdtemp, symlink, access, fileExists, readJSON, writeJSON, ensureDir, isDirEmpty, runCmd, } from './fs';
 export { escapeHtml, escapeHtmlAttr, escapeJsString, escapeScriptClose, safeJsonForScript } from './escape';
 export { safeStringify } from './serialization';
 export { getCrypto, rsaVerify, rsaVerifySync, pemToPublicJwk, generateRsaKeyPair, rsaSignBase64Url, type RsaJwk, type RsaKeyPair, jwtAlgToNodeAlg, isRsaPssAlg, randomUUID, randomBytes, sha256, sha256Hex, sha256Base64url, hmacSha256, hkdfSha256, encryptAesGcm, decryptAesGcm, timingSafeEqual, bytesToHex, base64urlEncode, base64urlDecode, base64Encode, base64Decode, isNode, isBrowser, assertNode, EncryptedBlobError, encryptValue, decryptValue, tryDecryptValue, serializeBlob, deserializeBlob, tryDeserializeBlob, isValidEncryptedBlob, encryptAndSerialize, deserializeAndDecrypt, tryDeserializeAndDecrypt, generateCodeVerifier, generateCodeChallenge, verifyCodeChallenge, generatePkcePair, isValidCodeVerifier, isValidCodeChallenge, MIN_CODE_VERIFIER_LENGTH, MAX_CODE_VERIFIER_LENGTH, DEFAULT_CODE_VERIFIER_LENGTH, PkceError, type PkcePair, type SecretData, type SecretPersistenceOptions, type SecretValidationResult, secretDataSchema, validateSecretData, parseSecretData, isSecretPersistenceEnabled, resolveSecretPath, loadSecret, saveSecret, deleteSecret, generateSecret, createSecretData, getOrCreateSecret, clearCachedSecret, isSecretCached, type SignedData, type HmacSigningConfig, signData, verifyData, isSignedData, verifyOrParseData, type BaseKeyData, type SecretKeyData, type AsymmetricKeyData, type AnyKeyData, type KeyPersistenceOptions, type CreateKeyPersistenceOptions, type CreateSecretOptions, type CreateAsymmetricOptions, type KeyValidationResult, asymmetricAlgSchema, secretKeyDataSchema, asymmetricKeyDataSchema, anyKeyDataSchema, validateKeyData, parseKeyData, isSecretKeyData, isAsymmetricKeyData, KeyPersistence, createKeyPersistence, createKeyPersistenceWithStorage, } from './crypto';
 export type { CryptoProvider, EncBlob, EncryptedBlob } from './crypto';
 export { AsyncLocalStorage } from './async-context';
 export { EventEmitter } from './event-emitter';
-export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, entryAvailabilitySchema, } from './env';
+export { getEnv, getCwd, isProduction, isDevelopment, getEnvFlag, isDebug, setEnv, isEdgeRuntime, isServerless, supportsAnsi, getRuntimeContext, resetRuntimeContext, detectRuntimeContext, isEntryAvailable, checkEntryAvailability, entryAvailabilitySchema, } from './env';
 export type { RuntimeContext, EntryAvailability } from './env';
 export { analyzePattern, isPatternSafe, createSafeRegExp, safeTest, safeMatch, safeReplace, safeExec, isInputLengthSafe, DEFAULT_MAX_INPUT_LENGTH, REDOS_THRESHOLDS, trimLeading, trimTrailing, trimBoth, trimChars, extractBracedParams, expandTemplate, hasTemplatePlaceholders, collapseChar, collapseWhitespace, type SafeRegexOptions, type PatternAnalysisResult, } from './regex';
 export { createStorage, createMemoryStorage, getDetectedStorageType, NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, type FileSystemAdapterOptions, TypedStorage, type TypedStorageOptions, type TypedSetOptions, type TypedSetEntry, EncryptedTypedStorage, type EncryptedTypedStorageOptions, type EncryptedSetOptions, type EncryptedSetEntry, type EncryptionKey, type StoredEncryptedBlob, type ClientKeyBinding, globToRegex, matchesPattern, validatePattern, escapeGlob, MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './storage';

package/index.js

@@ -75,8 +75,8 @@ async function readFile(p, encoding = "utf8") {
   return fsp.readFile(p, encoding);
 }
 function readFileSync(p, encoding = "utf8") {
-  const fs = getFs();
-  return fs.readFileSync(p, encoding);
+  const fs2 = getFs();
+  return fs2.readFileSync(p, encoding);
 }
 async function readFileBuffer(p) {
   const fsp = getFsp();
@@ -148,6 +148,10 @@ async function readdir(p) {
   const fsp = getFsp();
   return fsp.readdir(p);
 }
+function readdirSync(p) {
+  const fs2 = getFs();
+  return fs2.readdirSync(p);
+}
 async function rm(p, options) {
   const fsp = getFsp();
   await fsp.rm(p, options);
@@ -566,9 +570,9 @@ function createSecretData(options) {
 }
 async function getOrCreateSecret(options) {
   const cacheKey = resolveSecretPath(options);
-  const cached2 = secretCache.get(cacheKey);
-  if (cached2) {
-    return cached2;
+  const cached4 = secretCache.get(cacheKey);
+  if (cached4) {
+    return cached4;
   }
   const existing = generationPromises.get(cacheKey);
   if (existing) {
@@ -806,8 +810,8 @@ var init_key_persistence = __esm({
        */
       async get(kid) {
         if (this.enableCache) {
-          const cached2 = this.cache.get(kid);
-          if (cached2) return cached2;
+          const cached4 = this.cache.get(kid);
+          if (cached4) return cached4;
         }
         const raw = await this.storage.get(kid);
         if (!raw) return null;
@@ -3834,6 +3838,7 @@ __export(index_exports, {
   buildPrefix: () => buildPrefix,
   buildSetCookie: () => buildSetCookie,
   bytesToHex: () => bytesToHex,
+  checkEntryAvailability: () => checkEntryAvailability,
   clearCachedSecret: () => clearCachedSecret,
   collapseChar: () => collapseChar,
   collapseWhitespace: () => collapseWhitespace,
@@ -3935,6 +3940,7 @@ __export(index_exports, {
   parseUriTemplate: () => parseUriTemplate,
   pathJoin: () => import_path.join,
   pathResolve: () => import_path.resolve,
+  pathToFileURL: () => import_url.pathToFileURL,
   pemToPublicJwk: () => pemToPublicJwk2,
   processPlatformToolCalls: () => processPlatformToolCalls,
   randomBytes: () => randomBytes,
@@ -3944,6 +3950,7 @@ __export(index_exports, {
   readFileSync: () => readFileSync,
   readJSON: () => readJSON,
   readdir: () => readdir,
+  readdirSync: () => readdirSync,
   realpath: () => realpath,
   rename: () => rename,
   resetRuntimeContext: () => resetRuntimeContext,
@@ -4405,6 +4412,7 @@ function joinPath(...parts) {
 
 // libs/utils/src/path/node-path.ts
 var import_path = require("path");
+var import_url = require("url");
 
 // libs/utils/src/content/content.ts
 function sanitizeToJson(value) {
@@ -4692,23 +4700,114 @@ var import_env3 = require("#env");
 // libs/utils/src/env/runtime-context.ts
 var import_lazy_zod3 = require("@frontmcp/lazy-zod");
 var import_env2 = require("#env");
+
+// libs/utils/src/env/build-target.ts
+var cached;
+function getBuildTarget() {
+  if (cached) return cached;
+  cached = resolveBuildTarget();
+  return cached;
+}
+function resolveBuildTarget() {
+  const globalAny = globalThis;
+  const fromGlobal = globalAny.FRONTMCP_BUILD_TARGET;
+  if (typeof fromGlobal === "string" && isKnownTarget(fromGlobal)) return fromGlobal;
+  const fromEnv = typeof process !== "undefined" ? process.env?.["FRONTMCP_BUILD_TARGET"] : void 0;
+  if (typeof fromEnv === "string" && isKnownTarget(fromEnv)) return fromEnv;
+  return "unknown";
+}
+function isKnownTarget(value) {
+  return value === "unknown" || value === "node" || value === "distributed" || value === "cli" || value === "vercel" || value === "lambda" || value === "cloudflare" || value === "browser" || value === "sdk" || value === "mcpb";
+}
+
+// libs/utils/src/env/provider.ts
+var fs = __toESM(require("node:fs"));
+var cached2;
+function detectProvider() {
+  if (cached2) return cached2;
+  cached2 = detectProviderUncached();
+  return cached2;
+}
+function detectProviderUncached() {
+  const explicit = process.env["FRONTMCP_PROVIDER"];
+  if (explicit && isKnownProvider(explicit)) return explicit;
+  if (process.env["VERCEL"]) return "vercel";
+  if (process.env["AWS_LAMBDA_FUNCTION_NAME"]) return "lambda";
+  if (process.env["CF_PAGES"]) return "cloudflare";
+  if (process.env["NETLIFY"]) return "netlify";
+  if (process.env["AZURE_FUNCTIONS_ENVIRONMENT"]) return "azure";
+  if (process.env["K_SERVICE"]) return "gcp";
+  if (process.env["FLY_APP_NAME"]) return "fly";
+  if (process.env["RENDER"]) return "render";
+  if (process.env["RAILWAY_ENVIRONMENT"]) return "railway";
+  try {
+    if (fs.existsSync("/.dockerenv")) return "docker";
+  } catch {
+  }
+  return "bare";
+}
+function isKnownProvider(value) {
+  return value === "bare" || value === "docker" || value === "vercel" || value === "lambda" || value === "cloudflare" || value === "netlify" || value === "azure" || value === "gcp" || value === "fly" || value === "render" || value === "railway";
+}
+
+// libs/utils/src/env/runtime-context.ts
 var entryAvailabilitySchema = import_lazy_zod3.z.object({
+  os: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
   platform: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
   runtime: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
   deployment: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
+  provider: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
+  target: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional(),
+  surface: import_lazy_zod3.z.array(import_lazy_zod3.z.enum(["mcp", "cli", "http-trigger", "job", "agent"])).optional(),
   env: import_lazy_zod3.z.array(import_lazy_zod3.z.string().min(1)).optional()
 }).strict();
-function isEntryAvailable(availability, ctx) {
+var PROCESS_AXES = [
+  // `os` and `platform` both compare against the same RuntimeContext value
+  // — keeping `platform` as a deprecated alias lets pre-#417 metadata
+  // continue to match without any code change.
+  { key: "os", ctxKey: "os" },
+  { key: "platform", ctxKey: "platform" },
+  { key: "runtime", ctxKey: "runtime" },
+  { key: "deployment", ctxKey: "deployment" },
+  { key: "provider", ctxKey: "provider" },
+  { key: "target", ctxKey: "target" },
+  { key: "env", ctxKey: "env" }
+];
+function isEntryAvailable(availability, ctx, callCtx) {
   if (!availability) return true;
-  const fields = ["platform", "runtime", "deployment", "env"];
-  for (const field of fields) {
-    const allowed = availability[field];
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
     if (allowed === void 0) continue;
     if (allowed.length === 0) return false;
-    if (!allowed.includes(ctx[field])) return false;
+    if (!allowed.includes(ctx[ctxKey])) return false;
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) return false;
+    if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) {
+      return false;
+    }
   }
   return true;
 }
+function checkEntryAvailability(availability, ctx, callCtx) {
+  if (!availability) return { available: true, missingAxes: [] };
+  const missing = [];
+  for (const { key, ctxKey } of PROCESS_AXES) {
+    const allowed = availability[key];
+    if (allowed === void 0) continue;
+    if (allowed.length === 0 || !allowed.includes(ctx[ctxKey])) {
+      missing.push(key);
+    }
+  }
+  if (availability.surface !== void 0) {
+    if (availability.surface.length === 0) {
+      missing.push("surface");
+    } else if (callCtx?.surface !== void 0 && !availability.surface.includes(callCtx.surface)) {
+      missing.push("surface");
+    }
+  }
+  return { available: missing.length === 0, missingAxes: missing };
+}
 function detectRuntime() {
   if (typeof globalThis !== "undefined" && "Bun" in globalThis) return "bun";
   if (typeof globalThis !== "undefined" && "Deno" in globalThis) return "deno";
@@ -4725,22 +4824,26 @@ function detectDeployment(runtime) {
 }
 function detectRuntimeContext() {
   const runtime = detectRuntime();
+  const os = process.platform;
   return {
-    platform: process.platform,
+    os,
+    platform: os,
     runtime,
     deployment: detectDeployment(runtime),
+    provider: detectProvider(),
+    target: getBuildTarget(),
     env: process.env["NODE_ENV"] || "development"
   };
 }
-var cached;
+var cached3;
 function getRuntimeContext() {
-  if (!cached) {
-    cached = detectRuntimeContext();
+  if (!cached3) {
+    cached3 = detectRuntimeContext();
   }
-  return cached;
+  return cached3;
 }
 function resetRuntimeContext() {
-  cached = void 0;
+  cached3 = void 0;
 }
 
 // libs/utils/src/storage/factory.ts
@@ -5581,8 +5684,8 @@ function loadMachineIdSync() {
   if (!isDevPersistenceEnabled()) return null;
   const machineIdPath = resolveMachineIdPath();
   try {
-    const fs = require("fs");
-    const content = fs.readFileSync(machineIdPath, "utf8").trim();
+    const fs2 = require("fs");
+    const content = fs2.readFileSync(machineIdPath, "utf8").trim();
     if (/^[0-9a-f-]{32,36}$/i.test(content)) return content;
     console.warn(`[MachineId] Invalid format at ${machineIdPath}, will regenerate`);
     return null;
@@ -5682,6 +5785,7 @@ function setMachineIdOverride(id) {
   buildPrefix,
   buildSetCookie,
   bytesToHex,
+  checkEntryAvailability,
   clearCachedSecret,
   collapseChar,
   collapseWhitespace,
@@ -5783,6 +5887,7 @@ function setMachineIdOverride(id) {
   parseUriTemplate,
   pathJoin,
   pathResolve,
+  pathToFileURL,
   pemToPublicJwk,
   processPlatformToolCalls,
   randomBytes,
@@ -5792,6 +5897,7 @@ function setMachineIdOverride(id) {
   readFileSync,
   readJSON,
   readdir,
+  readdirSync,
   realpath,
   rename,
   resetRuntimeContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -34,7 +34,7 @@
   "peerDependencies": {
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0",
-    "@frontmcp/lazy-zod": "1.2.1"
+    "@frontmcp/lazy-zod": "1.3.0"
   },
   "peerDependenciesMeta": {
     "@vercel/kv": {

package/path/browser-path.d.ts

@@ -4,3 +4,4 @@ export declare function basename(p: string, ext?: string): string;
 export declare function dirname(_p: string): string;
 export declare function extname(p: string): string;
 export declare function isAbsolute(p: string): boolean;
+export declare function pathToFileURL(_p: string): URL;

package/path/index.d.ts

@@ -1,2 +1,2 @@
 export { trimSlashes, joinPath } from './path';
-export { resolve as pathResolve, join as pathJoin, basename, dirname, extname, isAbsolute } from '#path';
+export { resolve as pathResolve, join as pathJoin, basename, dirname, extname, isAbsolute, pathToFileURL } from '#path';

package/path/node-path.d.ts

@@ -1 +1,2 @@
 export { resolve, join, basename, dirname, extname, isAbsolute } from 'path';
+export { pathToFileURL } from 'url';