feat(manifest): add host-agnostic manifest template resolver

Extract the DriverContext-free $[file('...')] and ${{env}} resolution
logic into @microsoft/app-manifest so it can be consumed without
fx-core's DriverContext, i18n, or UserError dependencies.

Exports resolveManifestTemplate, expandFileFunctionMacros,
resolveManifestFunctionCall, expandEnvironmentVariable,
getEnvironmentVariables, the ManifestType enum, and typed error
classes carrying structured data fields. Uses only node:path and
node:fs/promises (no new dependencies).

Adds dedicated unit tests exercising file inlining, JSON escaping,
BOM/CRLF normalization, nested file() calls, env-as-parameter,
ApiSpec skip, and every typed error path.

Author: iclanton

packages/manifest/src/index.ts

@@ -21,6 +21,7 @@ import { PluginManifestSchema } from "./pluginManifest";
 export * from "./declarativeCopilotManifest";
 export * from "./generated-types";
 export * from "./manifest";
+export * from "./manifestTemplate";
 export * from "./pluginManifest";
 export * from "./wrappers";
 

packages/manifest/src/manifestTemplate.ts

@@ -0,0 +1,256 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// Host-agnostic resolution of manifest templating: the `${{ENV}}` environment
+// variable syntax and the `$[file('<path>')]` function syntax. This logic was
+// previously entangled with fx-core's DriverContext (telemetry, logging, i18n,
+// FxError). It is lifted here so that consumers such as the SPFx build pipeline
+// can resolve declarative-agent manifests offline without depending on
+// @microsoft/teamsfx-core or a DriverContext.
+
+import path from "path";
+import { readFile, stat } from "fs/promises";
+
+const placeholderRegex = /\${{ *[a-zA-Z_][a-zA-Z0-9_]* *}}/g;
+const functionRegex = /\$\[ *[a-zA-Z][a-zA-Z]*\([^\]]*\) *\]/g;
+
+export enum ManifestType {
+  TeamsManifest = "teams-manifest",
+  PluginManifest = "plugin-manifest",
+  DeclarativeCopilotManifest = "declarative-copilot-manifest",
+  ApiSpec = "api-spec",
+  EmbeddedKnowledgeFile = "embedded-knowledge-file",
+}
+
+export interface ResolveManifestOptions {
+  // Explicit environment map. When omitted, process.env is used.
+  envs?: { [key in string]: string };
+  // Absolute path of the manifest file being resolved. `file()` paths are
+  // resolved relative to this file's directory.
+  fromPath: string;
+  manifestType: ManifestType;
+  // Optional diagnostic sink, replacing DriverContext.logProvider.
+  logger?: { error: (message: string) => void };
+}
+
+// Base error for all template-resolution failures. Consumers can catch this to
+// distinguish resolution errors from unexpected exceptions.
+export class ManifestTemplateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ManifestTemplateError";
+  }
+}
+
+export class UnsupportedFileFormatError extends ManifestTemplateError {
+  constructor(public readonly filePath: string) {
+    super("The file to be embedded must be a .txt or .md file.");
+    this.name = "UnsupportedFileFormatError";
+  }
+}
+
+export class InvalidFunctionError extends ManifestTemplateError {
+  constructor(public readonly token: string) {
+    super("Unsupported function. Only the 'file' function is supported.");
+    this.name = "InvalidFunctionError";
+  }
+}
+
+export class InvalidFunctionParameterError extends ManifestTemplateError {
+  constructor(public readonly token: string) {
+    super("Invalid parameter for the 'file' function.");
+    this.name = "InvalidFunctionParameterError";
+  }
+}
+
+export class ReadFileError extends ManifestTemplateError {
+  constructor(
+    public readonly filePath: string,
+    public readonly cause?: unknown
+  ) {
+    super(`Failed to read file '${filePath}'.`);
+    this.name = "ReadFileError";
+  }
+}
+
+export class FileNotFoundError extends ManifestTemplateError {
+  constructor(public readonly filePath: string) {
+    super(`File not found: '${filePath}'.`);
+    this.name = "FileNotFoundError";
+  }
+}
+
+export class MissingEnvironmentVariablesError extends ManifestTemplateError {
+  constructor(public readonly names: string) {
+    super(`The following environment variables are not defined: ${names}.`);
+    this.name = "MissingEnvironmentVariablesError";
+  }
+}
+
+// Expand `${{ENV_NAME}}` references in content. Referencing a value not present
+// in `envs`/process.env leaves the placeholder untouched, except APP_NAME_SUFFIX
+// which is substituted when explicitly set (including empty string).
+export function expandEnvironmentVariable(
+  content: string,
+  envs?: { [key in string]: string }
+): string {
+  const placeholders = content.match(placeholderRegex);
+  if (placeholders) {
+    for (const placeholder of placeholders) {
+      const envName = placeholder.slice(3, -2).trim();
+      const envValue = envs ? envs[envName] : process.env[envName];
+      if (envName === "APP_NAME_SUFFIX") {
+        if (envValue !== undefined && envValue !== null) {
+          content = content.replace(placeholder, envValue);
+        }
+      } else {
+        if (envValue) {
+          content = content.replace(placeholder, envValue);
+        }
+      }
+    }
+  }
+  return content;
+}
+
+// Return the de-duplicated list of `${{ENV_NAME}}` variables referenced in content.
+export function getEnvironmentVariables(content: string): string[] {
+  const placeholders = content.match(placeholderRegex);
+  if (placeholders) {
+    const variables = placeholders.map((placeholder) => placeholder.slice(3, -2).trim());
+    return [...new Set(variables)];
+  }
+  return [];
+}
+
+function getAbsolutePath(relativeOrAbsolutePath: string, fromPath: string): string {
+  return path.isAbsolute(relativeOrAbsolutePath)
+    ? relativeOrAbsolutePath
+    : path.join(path.dirname(fromPath), relativeOrAbsolutePath);
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readFileContent(
+  filePath: string,
+  envs: { [key in string]: string } | undefined,
+  fromPath: string,
+  logger?: { error: (message: string) => void }
+): Promise<string> {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext !== ".txt" && ext !== ".md") {
+    logger?.error(`Unsupported file '${filePath}'. Only .txt and .md files are supported.`);
+    throw new UnsupportedFileFormatError(filePath);
+  }
+
+  const absolutePath = getAbsolutePath(filePath, fromPath);
+  if (await pathExists(absolutePath)) {
+    try {
+      let fileContent = await readFile(absolutePath, "utf8");
+      fileContent = fileContent.replace(/^\uFEFF/, "");
+      let processedFileContent = expandEnvironmentVariable(fileContent, envs);
+      processedFileContent = processedFileContent.replace(/\r\n/g, "\n");
+      return processedFileContent;
+    } catch (e) {
+      logger?.error(`Failed to read file '${absolutePath}': ${(e as Error)?.toString()}`);
+      throw new ReadFileError(absolutePath, e);
+    }
+  }
+  throw new FileNotFoundError(filePath);
+}
+
+// Resolve a single `file(...)` function body (the text inside `$[ ... ]`) to its
+// embedded, env-expanded file content. Exposed so consumers that need per-call
+// control (e.g. fx-core's telemetry/error-mapping loop) can delegate here.
+export async function resolveManifestFunctionCall(
+  content: string,
+  envs: { [key in string]: string } | undefined,
+  fromPath: string,
+  logger?: { error: (message: string) => void }
+): Promise<string> {
+  const firstTrimmedContent = content.trim();
+  if (!firstTrimmedContent.startsWith("file(") || !firstTrimmedContent.endsWith(")")) {
+    logger?.error(`Unsupported function '${firstTrimmedContent}'. Only 'file' is supported.`);
+    throw new InvalidFunctionError(firstTrimmedContent);
+  }
+
+  const trimmedParameter = content.slice(5, -1).trim();
+  if (trimmedParameter[0] === "'" && trimmedParameter[trimmedParameter.length - 1] === "'") {
+    // static string parameter
+    return readFileContent(
+      trimmedParameter.substring(1, trimmedParameter.length - 1),
+      envs,
+      fromPath,
+      logger
+    );
+  } else if (trimmedParameter.startsWith("${{") && trimmedParameter.endsWith("}}")) {
+    // env variable inside
+    const resolvedParameter = expandEnvironmentVariable(trimmedParameter, envs);
+    return readFileContent(resolvedParameter, envs, fromPath, logger);
+  } else if (trimmedParameter.startsWith("file(") && trimmedParameter.endsWith(")")) {
+    // nested function inside
+    const nested = await resolveManifestFunctionCall(trimmedParameter, envs, fromPath, logger);
+    return readFileContent(nested, envs, fromPath, logger);
+  } else {
+    logger?.error(`Invalid parameter '${trimmedParameter}' for the 'file' function.`);
+    throw new InvalidFunctionParameterError(trimmedParameter);
+  }
+}
+
+// Expand `$[file('<path>')]` function calls in content. When `isJson` is true the
+// embedded content is JSON-string escaped so it can be inlined into a JSON string.
+export async function expandFileFunctionMacros(
+  content: string,
+  isJson: boolean,
+  options: Pick<ResolveManifestOptions, "envs" | "fromPath" | "logger">
+): Promise<string> {
+  const matches = content.match(functionRegex);
+  if (!matches) {
+    return content;
+  }
+  for (const placeholder of matches) {
+    let value = await resolveManifestFunctionCall(
+      placeholder.slice(2, -1).trim(),
+      options.envs,
+      options.fromPath,
+      options.logger
+    );
+    if (isJson && value) {
+      value = JSON.stringify(value).slice(1, -1);
+    }
+    if (value) {
+      content = content.replace(placeholder, value);
+    }
+  }
+  return content;
+}
+
+// Fully resolve a manifest template string: expand `$[file()]` functions (except
+// for ApiSpec) then `${{ENV}}` variables, and fail if any variable is left
+// unresolved. Mirrors fx-core's getResolvedManifest without telemetry or a
+// DriverContext.
+export async function resolveManifestTemplate(
+  content: string,
+  options: ResolveManifestOptions
+): Promise<string> {
+  let value = content;
+  if (options.manifestType !== ManifestType.ApiSpec) {
+    value = await expandFileFunctionMacros(content, true, options);
+    value = expandEnvironmentVariable(value, options.envs);
+  } else {
+    value = expandEnvironmentVariable(value, options.envs);
+  }
+
+  const notExpandedVars = getEnvironmentVariables(value);
+  if (notExpandedVars.length > 0) {
+    throw new MissingEnvironmentVariablesError(notExpandedVars.join(","));
+  }
+  return value;
+}