@backstage/plugin-techdocs-node 0.0.0-nightly-20260818023149 → 0.0.0-nightly-20260829022506

package/CHANGELOG.md

@@ -1,20 +1,36 @@
 # @backstage/plugin-techdocs-node
 
-## 0.0.0-nightly-20260818023149
+## 0.0.0-nightly-20260829022506
 
 ### Patch Changes
 
-- 226817d: chore(deps): bump `js-yaml` from 4.2.0 to 4.3.0
+- e58d265: Updated TechDocs generation to reject source trees containing symlinks that resolve outside the source directory.
+- d13ad29: Improved MkDocs configuration handling for additional templates.
+- 2233af2: Improved MkDocs configuration sanitization to cover additional nested configuration keys and theme options.
+- 4441911: Improved MkDocs configuration file handling.
+- 45cbd0a: Improved validation of MkDocs configuration values during TechDocs generation.
+- 030331b: Improved file validation in the local TechDocs publisher during the publish step.
 - Updated dependencies
-  - @backstage/catalog-model@0.0.0-nightly-20260818023149
-  - @backstage/backend-plugin-api@0.0.0-nightly-20260818023149
-  - @backstage/integration@0.0.0-nightly-20260818023149
-  - @backstage/integration-aws-node@0.0.0-nightly-20260818023149
+  - @backstage/integration@0.0.0-nightly-20260829022506
+  - @backstage/backend-plugin-api@1.10.0
+  - @backstage/catalog-model@1.10.0
   - @backstage/config@1.3.8
-  - @backstage/plugin-search-common@0.0.0-nightly-20260818023149
   - @backstage/errors@1.3.1
+  - @backstage/integration-aws-node@0.2.1
+  - @backstage/plugin-search-common@1.2.24
   - @backstage/plugin-techdocs-common@0.1.1
 
+## 1.15.3
+
+### Patch Changes
+
+- 226817d: chore(deps): bump `js-yaml` from 4.2.0 to 4.3.0
+- Updated dependencies
+  - @backstage/catalog-model@1.10.0
+  - @backstage/backend-plugin-api@1.10.0
+  - @backstage/integration@2.1.0
+  - @backstage/integration-aws-node@0.2.1
+
 ## 1.15.3-next.1
 
 ### Patch Changes

package/dist/stages/generate/helpers.cjs.js

@@ -71,10 +71,18 @@ const getRepoUrlFromLocationAnnotation = (parsedLocationAnnotation, scmIntegrati
   }
   return {};
 };
+const ALLOWED_PYTHON_YAML_TAGS = /* @__PURE__ */ new Set([
+  "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+  "tag:yaml.org,2002:python/object.apply:materialx.emoji.to_svg",
+  "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify"
+]);
 class UnknownTag {
   data;
   type;
   constructor(data, type) {
+    if (type?.startsWith("tag:yaml.org,2002:python/") && !ALLOWED_PYTHON_YAML_TAGS.has(type)) {
+      throw new Error(`Unsupported Python YAML tag '${type}'`);
+    }
     this.data = data;
     this.type = type;
   }
@@ -194,7 +202,6 @@ const ALLOWED_MKDOCS_KEYS = /* @__PURE__ */ new Set([
   "markdown_extensions",
   "extra",
   "extra_css",
-  "extra_templates",
   // Preview controls
   "use_directory_urls",
   "strict",
@@ -208,6 +215,18 @@ const ALLOWED_MKDOCS_KEYS = /* @__PURE__ */ new Set([
   // Deprecated
   "google_analytics"
 ]);
+const DANGEROUS_EXTENSION_CONFIG_KEYS = /* @__PURE__ */ new Set(["plantuml_cmd"]);
+const ALLOWED_THEME_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "font",
+  "icon",
+  "logo",
+  "favicon",
+  "language",
+  "direction",
+  "palette",
+  "features"
+]);
 const validateMkdocsYaml = async (inputDir, mkdocsYmlFileString) => {
   const mkdocsYml = yaml__default.default.load(mkdocsYmlFileString, {
     schema: MKDOCS_SCHEMA
@@ -224,12 +243,19 @@ const validateMkdocsYaml = async (inputDir, mkdocsYmlFileString) => {
   }
   return parsedMkdocsYml.docs_dir;
 };
-const validateDocsDirectory = async (docsDir, inputDir) => {
-  const files = await helpers.getFileTreeRecursively(docsDir);
-  for (const file of files) {
-    if (!backendPluginApi.isChildPath(inputDir, file)) {
+const validateInputDirectory = async (inputDir) => {
+  const entries = await fs__default.default.readdir(inputDir, {
+    recursive: true,
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    if (!entry.isSymbolicLink()) {
+      continue;
+    }
+    const entryPath = path__default.default.join(entry.parentPath, entry.name);
+    if (!backendPluginApi.isChildPath(inputDir, entryPath)) {
       throw new errors.NotAllowedError(
-        `Path ${file} is not allowed to refer to a location outside ${inputDir}`
+        `Path ${entryPath} is not allowed to refer to a location outside ${inputDir}`
       );
     }
   }
@@ -313,6 +339,8 @@ const storeEtagMetadata = async (techdocsMetadataPath, etag) => {
 };
 
 exports.ALLOWED_MKDOCS_KEYS = ALLOWED_MKDOCS_KEYS;
+exports.ALLOWED_THEME_KEYS = ALLOWED_THEME_KEYS;
+exports.DANGEROUS_EXTENSION_CONFIG_KEYS = DANGEROUS_EXTENSION_CONFIG_KEYS;
 exports.MKDOCS_SCHEMA = MKDOCS_SCHEMA;
 exports.createOrUpdateMetadata = createOrUpdateMetadata;
 exports.generateMkdocsYml = generateMkdocsYml;
@@ -322,6 +350,6 @@ exports.getRepoUrlFromLocationAnnotation = getRepoUrlFromLocationAnnotation;
 exports.patchIndexPreBuild = patchIndexPreBuild;
 exports.runCommand = runCommand;
 exports.storeEtagMetadata = storeEtagMetadata;
-exports.validateDocsDirectory = validateDocsDirectory;
+exports.validateInputDirectory = validateInputDirectory;
 exports.validateMkdocsYaml = validateMkdocsYaml;
 //# sourceMappingURL=helpers.cjs.js.map

package/dist/stages/generate/helpers.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.cjs.js","sources":["../../../src/stages/generate/helpers.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { isChildPath, LoggerService } from '@backstage/backend-plugin-api';\nimport { Entity } from '@backstage/catalog-model';\nimport { ForwardedError, NotAllowedError, toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { SpawnOptionsWithoutStdio, spawn } from 'node:child_process';\nimport fs from 'fs-extra';\nimport gitUrlParse from 'git-url-parse';\nimport yaml, { DEFAULT_SCHEMA, Type } from 'js-yaml';\nimport path, { resolve as resolvePath } from 'node:path';\nimport { PassThrough, Writable } from 'node:stream';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport { DefaultMkdocsContent, SupportedGeneratorKey } from './types';\nimport { getFileTreeRecursively } from '../publish/helpers';\n\n// TODO: Implement proper support for more generators.\nexport function getGeneratorKey(entity: Entity): SupportedGeneratorKey {\n  if (!entity) {\n    throw new Error('No entity provided');\n  }\n\n  return 'techdocs';\n}\n\nexport type RunCommandOptions = {\n  /** command to run */\n  command: string;\n  /** arguments to pass the command */\n  args: string[];\n  /** options to pass to spawn */\n  options: SpawnOptionsWithoutStdio;\n  /** stream to capture stdout and stderr output */\n  logStream?: Writable;\n};\n\n/**\n * Run a command in a sub-process, normally a shell command.\n */\nexport const runCommand = async ({\n  command,\n  args,\n  options,\n  logStream = new PassThrough(),\n}: RunCommandOptions) => {\n  await new Promise<void>((resolve, reject) => {\n    const process = spawn(command, args, options);\n\n    process.stdout.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.stderr.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.on('error', error => {\n      return reject(error);\n    });\n\n    process.on('close', code => {\n      if (code !== 0) {\n        return reject(`Command ${command} failed, exit code: ${code}`);\n      }\n      return resolve();\n    });\n  });\n};\n\n/**\n * Return the source url for MkDocs based on the backstage.io/techdocs-ref annotation.\n * Depending on the type of target, it can either return a repo_url, an edit_uri, both, or none.\n *\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n * @param docsFolder - the configured docs folder in the mkdocs.yml (defaults to 'docs')\n * @returns the settings for the mkdocs.yml\n */\nexport const getRepoUrlFromLocationAnnotation = (\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n  docsFolder: string = 'docs',\n): { repo_url?: string; edit_uri?: string } => {\n  const { type: locationType, target } = parsedLocationAnnotation;\n\n  if (locationType === 'url') {\n    const integration = scmIntegrations.byUrl(target);\n\n    // We only support it for github, gitlab, bitbucketServer and harness for now as the edit_uri\n    // is not properly supported for others yet.\n    if (\n      integration &&\n      ['github', 'gitlab', 'bitbucketServer', 'harness'].includes(\n        integration.type,\n      )\n    ) {\n      // handle the case where a user manually writes url:https://github.com/backstage/backstage i.e. without /blob/...\n      const { filepathtype } = gitUrlParse(target);\n      if (filepathtype === '') {\n        return { repo_url: target };\n      }\n\n      const sourceFolder = integration.resolveUrl({\n        url: `./${docsFolder}`,\n        base: target.endsWith('/') ? target : `${target}/`,\n      });\n      return {\n        repo_url: target,\n        edit_uri: integration.resolveEditUrl(sourceFolder),\n      };\n    }\n  }\n\n  return {};\n};\n\nclass UnknownTag {\n  public readonly data: any;\n  public readonly type?: string;\n\n  constructor(data: any, type?: string) {\n    this.data = data;\n    this.type = type;\n  }\n}\n\nexport const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([\n  new Type('', {\n    kind: 'scalar',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('tag:', {\n    kind: 'mapping',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('', {\n    kind: 'sequence',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n]);\n\n/**\n * Generates a mkdocs.yml configuration file\n *\n * @param inputDir - base dir to where the mkdocs.yml file will be created\n * @param siteOptions - options for the site: `name` property will be used in mkdocs.yml for the\n * required `site_name` property, default value is \"Documentation Site\"\n */\nexport const generateMkdocsYml = async (\n  inputDir: string,\n  siteOptions?: { name?: string },\n) => {\n  try {\n    // TODO(awanlin): Use a provided default mkdocs.yml\n    // from config or some specified location. If this is\n    // not provided then fall back to generating bare\n    // minimum mkdocs.yml file\n\n    const mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    const defaultSiteName = siteOptions?.name ?? 'Documentation Site';\n    const defaultMkdocsContent: DefaultMkdocsContent = {\n      site_name: defaultSiteName,\n      docs_dir: 'docs',\n      plugins: ['techdocs-core'],\n    };\n\n    await fs.writeFile(\n      mkdocsYmlPath,\n      yaml.dump(defaultMkdocsContent, { schema: MKDOCS_SCHEMA }),\n    );\n  } catch (error) {\n    throw new ForwardedError('Could not generate mkdocs.yml file', error);\n  }\n};\n\n/**\n * Finds and loads the contents of an mkdocs.yml, mkdocs.yaml file, a file\n * with a specified name or an ad-hoc created file with minimal config.\n * @public\n *\n * @param inputDir - base dir to be searched for either an mkdocs.yml or mkdocs.yaml file.\n * @param options - name: default mkdocs site_name to be used with a ad hoc file default value is \"Documentation Site\"\n *                  mkdocsConfigFileName (optional): a non-default file name to be used as the config\n */\nexport const getMkdocsYml = async (\n  inputDir: string,\n  options?: { name?: string; mkdocsConfigFileName?: string },\n): Promise<{ path: string; content: string; configIsTemporary: boolean }> => {\n  let mkdocsYmlPath: string;\n  let mkdocsYmlFileString: string;\n  try {\n    if (options?.mkdocsConfigFileName) {\n      mkdocsYmlPath = path.join(inputDir, options.mkdocsConfigFileName);\n      if (!(await fs.pathExists(mkdocsYmlPath))) {\n        throw new Error(`The specified file ${mkdocsYmlPath} does not exist`);\n      }\n\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yaml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    // No mkdocs file, generate it\n    await generateMkdocsYml(inputDir, options);\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    throw new ForwardedError(\n      'Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml or default for validation',\n      error,\n    );\n  }\n\n  return {\n    path: mkdocsYmlPath,\n    content: mkdocsYmlFileString,\n    configIsTemporary: true,\n  };\n};\n\n/**\n * Allowlist of MkDocs configuration keys supported by TechDocs.\n *\n * @see https://www.mkdocs.org/user-guide/configuration/\n */\nexport const ALLOWED_MKDOCS_KEYS = new Set([\n  // Site information\n  'site_name',\n  'site_url',\n  'site_description',\n  'site_author',\n  // Repository\n  'repo_url',\n  'repo_name',\n  'edit_uri',\n  'edit_uri_template',\n  // Build directories\n  'docs_dir',\n  'site_dir',\n  // Documentation layout\n  'nav',\n  'exclude_docs',\n  'not_in_nav',\n  // Build settings\n  'theme',\n  'plugins',\n  'markdown_extensions',\n  'extra',\n  'extra_css',\n  'extra_templates',\n  // Preview controls\n  'use_directory_urls',\n  'strict',\n  'dev_addr',\n  'watch',\n  // Metadata\n  'copyright',\n  'remote_branch',\n  'remote_name',\n  'validation',\n  // Deprecated\n  'google_analytics',\n]);\n\n/**\n * Validating mkdocs config file for incorrect/insecure values\n * Throws on invalid configs\n *\n * @param inputDir - base dir to be used as a docs_dir path validity check\n * @param mkdocsYmlFileString - The string contents of the loaded\n *   mkdocs.yml or equivalent of a docs site\n * @returns the parsed docs_dir or undefined\n */\nexport const validateMkdocsYaml = async (\n  inputDir: string,\n  mkdocsYmlFileString: string,\n): Promise<string | undefined> => {\n  const mkdocsYml = yaml.load(mkdocsYmlFileString, {\n    schema: MKDOCS_SCHEMA,\n  });\n\n  if (mkdocsYml === null || typeof mkdocsYml !== 'object') {\n    return undefined;\n  }\n\n  const parsedMkdocsYml: Record<string, any> = mkdocsYml;\n\n  if (\n    parsedMkdocsYml.docs_dir &&\n    !isChildPath(inputDir, resolvePath(inputDir, parsedMkdocsYml.docs_dir))\n  ) {\n    throw new Error(\n      `docs_dir configuration value in mkdocs can't be an absolute directory or start with ../ for security reasons.\n       Use relative paths instead which are resolved relative to your mkdocs.yml file location.`,\n    );\n  }\n  return parsedMkdocsYml.docs_dir;\n};\n\n/**\n * Validates that the docs directory doesn't contain symlinks pointing outside\n * the input directory. This prevents path traversal attacks where malicious\n * symlinks could be used to read arbitrary files from the host filesystem.\n *\n * @param docsDir - The docs directory to validate (absolute path)\n * @param inputDir - The root input directory that symlinks must stay within\n */\nexport const validateDocsDirectory = async (\n  docsDir: string,\n  inputDir: string,\n): Promise<void> => {\n  const files = await getFileTreeRecursively(docsDir);\n\n  for (const file of files) {\n    if (!isChildPath(inputDir, file)) {\n      throw new NotAllowedError(\n        `Path ${file} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n  }\n};\n\n/**\n * Update docs/index.md file before TechDocs generator uses it to generate docs site,\n * falling back to docs/README.md or README.md in case a default docs/index.md\n * is not provided.\n */\nexport const patchIndexPreBuild = async ({\n  inputDir,\n  logger,\n  docsDir = 'docs',\n}: {\n  inputDir: string;\n  logger: LoggerService;\n  docsDir?: string;\n}) => {\n  const docsPath = path.join(inputDir, docsDir);\n  const indexMdPath = path.join(docsPath, 'index.md');\n\n  if (await fs.pathExists(indexMdPath)) {\n    return;\n  }\n  logger.warn(`${path.join(docsDir, 'index.md')} not found.`);\n  const fallbacks = [\n    path.join(docsPath, 'README.md'),\n    path.join(docsPath, 'readme.md'),\n    path.join(inputDir, 'README.md'),\n    path.join(inputDir, 'readme.md'),\n  ];\n\n  if (!isChildPath(inputDir, docsPath)) {\n    throw new NotAllowedError(\n      `Target path ${docsPath} is not allowed to refer to a location outside ${inputDir}`,\n    );\n  }\n  await fs.ensureDir(docsPath);\n  for (const filePath of fallbacks) {\n    if (!isChildPath(inputDir, filePath)) {\n      throw new NotAllowedError(\n        `Source path ${filePath} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n    try {\n      await fs.copyFile(filePath, indexMdPath);\n      return;\n    } catch (error) {\n      logger.warn(`${path.relative(inputDir, filePath)} not found.`);\n    }\n  }\n\n  logger.warn(\n    `Could not find any techdocs' index file. Please make sure at least one of ${[\n      indexMdPath,\n      ...fallbacks,\n    ].join(' ')} exists.`,\n  );\n};\n\n/**\n * Create or update the techdocs_metadata.json. Values initialized/updated are:\n * - The build_timestamp (now)\n * - The list of files generated\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n */\nexport const createOrUpdateMetadata = async (\n  techdocsMetadataPath: string,\n  logger: LoggerService,\n): Promise<void> => {\n  const techdocsMetadataDir = techdocsMetadataPath\n    .split(path.sep)\n    .slice(0, -1)\n    .join(path.sep);\n  // check if file exists, create if it does not.\n  try {\n    await fs.access(techdocsMetadataPath, fs.constants.F_OK);\n  } catch (err) {\n    // Bootstrap file with empty JSON\n    await fs.writeJson(techdocsMetadataPath, JSON.parse('{}'));\n  }\n  // check if valid Json\n  let json;\n  try {\n    json = await fs.readJson(techdocsMetadataPath);\n  } catch (err) {\n    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${\n      toError(err).message\n    }`;\n    logger.error(message);\n    throw new Error(message);\n  }\n\n  json.build_timestamp = Date.now();\n\n  // Get and write generated files to the metadata JSON. Each file string is in\n  // a form appropriate for invalidating the associated object from cache.\n  try {\n    json.files = (await getFileTreeRecursively(techdocsMetadataDir)).map(file =>\n      file.replace(`${techdocsMetadataDir}${path.sep}`, ''),\n    );\n  } catch (err) {\n    json.files = [];\n    logger.warn(\n      `Unable to add files list to metadata: ${toError(err).message}`,\n    );\n  }\n\n  await fs.writeJson(techdocsMetadataPath, json);\n  return;\n};\n\n/**\n * Update the techdocs_metadata.json to add etag of the prepared tree (e.g. commit SHA or actual Etag of the resource).\n * This is helpful to check if a TechDocs site in storage has gone outdated, without maintaining an in-memory build info\n * per Backstage instance.\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n * @param etag - The ETag to use\n */\nexport const storeEtagMetadata = async (\n  techdocsMetadataPath: string,\n  etag: string,\n): Promise<void> => {\n  const json = await fs.readJson(techdocsMetadataPath);\n  json.etag = etag;\n  await fs.writeJson(techdocsMetadataPath, json);\n};\n"],"names":["PassThrough","spawn","gitUrlParse","DEFAULT_SCHEMA","Type","path","fs","yaml","ForwardedError","isChildPath","resolvePath","getFileTreeRecursively","NotAllowedError","toError"],"mappings":"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"}
+{"version":3,"file":"helpers.cjs.js","sources":["../../../src/stages/generate/helpers.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { isChildPath, LoggerService } from '@backstage/backend-plugin-api';\nimport { Entity } from '@backstage/catalog-model';\nimport { ForwardedError, NotAllowedError, toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { SpawnOptionsWithoutStdio, spawn } from 'node:child_process';\nimport fs from 'fs-extra';\nimport gitUrlParse from 'git-url-parse';\nimport yaml, { DEFAULT_SCHEMA, Type } from 'js-yaml';\nimport path, { resolve as resolvePath } from 'node:path';\nimport { PassThrough, Writable } from 'node:stream';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport { DefaultMkdocsContent, SupportedGeneratorKey } from './types';\nimport { getFileTreeRecursively } from '../publish/helpers';\n\n// TODO: Implement proper support for more generators.\nexport function getGeneratorKey(entity: Entity): SupportedGeneratorKey {\n  if (!entity) {\n    throw new Error('No entity provided');\n  }\n\n  return 'techdocs';\n}\n\nexport type RunCommandOptions = {\n  /** command to run */\n  command: string;\n  /** arguments to pass the command */\n  args: string[];\n  /** options to pass to spawn */\n  options: SpawnOptionsWithoutStdio;\n  /** stream to capture stdout and stderr output */\n  logStream?: Writable;\n};\n\n/**\n * Run a command in a sub-process, normally a shell command.\n */\nexport const runCommand = async ({\n  command,\n  args,\n  options,\n  logStream = new PassThrough(),\n}: RunCommandOptions) => {\n  await new Promise<void>((resolve, reject) => {\n    const process = spawn(command, args, options);\n\n    process.stdout.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.stderr.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.on('error', error => {\n      return reject(error);\n    });\n\n    process.on('close', code => {\n      if (code !== 0) {\n        return reject(`Command ${command} failed, exit code: ${code}`);\n      }\n      return resolve();\n    });\n  });\n};\n\n/**\n * Return the source url for MkDocs based on the backstage.io/techdocs-ref annotation.\n * Depending on the type of target, it can either return a repo_url, an edit_uri, both, or none.\n *\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n * @param docsFolder - the configured docs folder in the mkdocs.yml (defaults to 'docs')\n * @returns the settings for the mkdocs.yml\n */\nexport const getRepoUrlFromLocationAnnotation = (\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n  docsFolder: string = 'docs',\n): { repo_url?: string; edit_uri?: string } => {\n  const { type: locationType, target } = parsedLocationAnnotation;\n\n  if (locationType === 'url') {\n    const integration = scmIntegrations.byUrl(target);\n\n    // We only support it for github, gitlab, bitbucketServer and harness for now as the edit_uri\n    // is not properly supported for others yet.\n    if (\n      integration &&\n      ['github', 'gitlab', 'bitbucketServer', 'harness'].includes(\n        integration.type,\n      )\n    ) {\n      // handle the case where a user manually writes url:https://github.com/backstage/backstage i.e. without /blob/...\n      const { filepathtype } = gitUrlParse(target);\n      if (filepathtype === '') {\n        return { repo_url: target };\n      }\n\n      const sourceFolder = integration.resolveUrl({\n        url: `./${docsFolder}`,\n        base: target.endsWith('/') ? target : `${target}/`,\n      });\n      return {\n        repo_url: target,\n        edit_uri: integration.resolveEditUrl(sourceFolder),\n      };\n    }\n  }\n\n  return {};\n};\n\nconst ALLOWED_PYTHON_YAML_TAGS = new Set([\n  'tag:yaml.org,2002:python/name:materialx.emoji.twemoji',\n  'tag:yaml.org,2002:python/object.apply:materialx.emoji.to_svg',\n  'tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify',\n]);\n\nclass UnknownTag {\n  public readonly data: any;\n  public readonly type?: string;\n\n  constructor(data: any, type?: string) {\n    if (\n      type?.startsWith('tag:yaml.org,2002:python/') &&\n      !ALLOWED_PYTHON_YAML_TAGS.has(type)\n    ) {\n      throw new Error(`Unsupported Python YAML tag '${type}'`);\n    }\n\n    this.data = data;\n    this.type = type;\n  }\n}\n\nexport const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([\n  new Type('', {\n    kind: 'scalar',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('tag:', {\n    kind: 'mapping',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('', {\n    kind: 'sequence',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n]);\n\n/**\n * Generates a mkdocs.yml configuration file\n *\n * @param inputDir - base dir to where the mkdocs.yml file will be created\n * @param siteOptions - options for the site: `name` property will be used in mkdocs.yml for the\n * required `site_name` property, default value is \"Documentation Site\"\n */\nexport const generateMkdocsYml = async (\n  inputDir: string,\n  siteOptions?: { name?: string },\n) => {\n  try {\n    // TODO(awanlin): Use a provided default mkdocs.yml\n    // from config or some specified location. If this is\n    // not provided then fall back to generating bare\n    // minimum mkdocs.yml file\n\n    const mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    const defaultSiteName = siteOptions?.name ?? 'Documentation Site';\n    const defaultMkdocsContent: DefaultMkdocsContent = {\n      site_name: defaultSiteName,\n      docs_dir: 'docs',\n      plugins: ['techdocs-core'],\n    };\n\n    await fs.writeFile(\n      mkdocsYmlPath,\n      yaml.dump(defaultMkdocsContent, { schema: MKDOCS_SCHEMA }),\n    );\n  } catch (error) {\n    throw new ForwardedError('Could not generate mkdocs.yml file', error);\n  }\n};\n\n/**\n * Finds and loads the contents of an mkdocs.yml, mkdocs.yaml file, a file\n * with a specified name or an ad-hoc created file with minimal config.\n * @public\n *\n * @param inputDir - base dir to be searched for either an mkdocs.yml or mkdocs.yaml file.\n * @param options - name: default mkdocs site_name to be used with a ad hoc file default value is \"Documentation Site\"\n *                  mkdocsConfigFileName (optional): a non-default file name to be used as the config\n */\nexport const getMkdocsYml = async (\n  inputDir: string,\n  options?: { name?: string; mkdocsConfigFileName?: string },\n): Promise<{ path: string; content: string; configIsTemporary: boolean }> => {\n  let mkdocsYmlPath: string;\n  let mkdocsYmlFileString: string;\n  try {\n    if (options?.mkdocsConfigFileName) {\n      mkdocsYmlPath = path.join(inputDir, options.mkdocsConfigFileName);\n      if (!(await fs.pathExists(mkdocsYmlPath))) {\n        throw new Error(`The specified file ${mkdocsYmlPath} does not exist`);\n      }\n\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yaml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    // No mkdocs file, generate it\n    await generateMkdocsYml(inputDir, options);\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    throw new ForwardedError(\n      'Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml or default for validation',\n      error,\n    );\n  }\n\n  return {\n    path: mkdocsYmlPath,\n    content: mkdocsYmlFileString,\n    configIsTemporary: true,\n  };\n};\n\n/**\n * Allowlist of MkDocs configuration keys supported by TechDocs.\n *\n * @see https://www.mkdocs.org/user-guide/configuration/\n */\nexport const ALLOWED_MKDOCS_KEYS = new Set([\n  // Site information\n  'site_name',\n  'site_url',\n  'site_description',\n  'site_author',\n  // Repository\n  'repo_url',\n  'repo_name',\n  'edit_uri',\n  'edit_uri_template',\n  // Build directories\n  'docs_dir',\n  'site_dir',\n  // Documentation layout\n  'nav',\n  'exclude_docs',\n  'not_in_nav',\n  // Build settings\n  'theme',\n  'plugins',\n  'markdown_extensions',\n  'extra',\n  'extra_css',\n  // Preview controls\n  'use_directory_urls',\n  'strict',\n  'dev_addr',\n  'watch',\n  // Metadata\n  'copyright',\n  'remote_branch',\n  'remote_name',\n  'validation',\n  // Deprecated\n  'google_analytics',\n]);\n\n/**\n * Denylist of configuration keys that must be stripped from extension\n * configurations nested within `markdown_extensions`.\n */\nexport const DANGEROUS_EXTENSION_CONFIG_KEYS = new Set(['plantuml_cmd']);\n\n/**\n * Allowlist of theme configuration keys supported by TechDocs.\n *\n * @see https://squidfunk.github.io/mkdocs-material/setup/\n */\nexport const ALLOWED_THEME_KEYS = new Set([\n  'name',\n  'font',\n  'icon',\n  'logo',\n  'favicon',\n  'language',\n  'direction',\n  'palette',\n  'features',\n]);\n\n/**\n * Validating mkdocs config file for incorrect/insecure values\n * Throws on invalid configs\n *\n * @param inputDir - base dir to be used as a docs_dir path validity check\n * @param mkdocsYmlFileString - The string contents of the loaded\n *   mkdocs.yml or equivalent of a docs site\n * @returns the parsed docs_dir or undefined\n */\nexport const validateMkdocsYaml = async (\n  inputDir: string,\n  mkdocsYmlFileString: string,\n): Promise<string | undefined> => {\n  const mkdocsYml = yaml.load(mkdocsYmlFileString, {\n    schema: MKDOCS_SCHEMA,\n  });\n\n  if (mkdocsYml === null || typeof mkdocsYml !== 'object') {\n    return undefined;\n  }\n\n  const parsedMkdocsYml: Record<string, any> = mkdocsYml;\n\n  if (\n    parsedMkdocsYml.docs_dir &&\n    !isChildPath(inputDir, resolvePath(inputDir, parsedMkdocsYml.docs_dir))\n  ) {\n    throw new Error(\n      `docs_dir configuration value in mkdocs can't be an absolute directory or start with ../ for security reasons.\n       Use relative paths instead which are resolved relative to your mkdocs.yml file location.`,\n    );\n  }\n  return parsedMkdocsYml.docs_dir;\n};\n\n/**\n * Validates that the input directory doesn't contain symlinks pointing outside\n * of it. This prevents path traversal attacks where malicious symlinks could be\n * used to read arbitrary files from the host filesystem.\n *\n * The whole input directory is checked rather than only the docs directory,\n * because MkDocs extensions can read files from anywhere in the input directory.\n *\n * @param inputDir - The input directory to validate (absolute path)\n */\nexport const validateInputDirectory = async (\n  inputDir: string,\n): Promise<void> => {\n  const entries = await fs.readdir(inputDir, {\n    recursive: true,\n    withFileTypes: true,\n  });\n\n  for (const entry of entries) {\n    if (!entry.isSymbolicLink()) {\n      continue;\n    }\n\n    const entryPath = path.join(entry.parentPath, entry.name);\n    // isChildPath resolves both paths through realpath, so this also catches\n    // relative, chained and dangling links\n    if (!isChildPath(inputDir, entryPath)) {\n      throw new NotAllowedError(\n        `Path ${entryPath} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n  }\n};\n\n/**\n * Update docs/index.md file before TechDocs generator uses it to generate docs site,\n * falling back to docs/README.md or README.md in case a default docs/index.md\n * is not provided.\n */\nexport const patchIndexPreBuild = async ({\n  inputDir,\n  logger,\n  docsDir = 'docs',\n}: {\n  inputDir: string;\n  logger: LoggerService;\n  docsDir?: string;\n}) => {\n  const docsPath = path.join(inputDir, docsDir);\n  const indexMdPath = path.join(docsPath, 'index.md');\n\n  if (await fs.pathExists(indexMdPath)) {\n    return;\n  }\n  logger.warn(`${path.join(docsDir, 'index.md')} not found.`);\n  const fallbacks = [\n    path.join(docsPath, 'README.md'),\n    path.join(docsPath, 'readme.md'),\n    path.join(inputDir, 'README.md'),\n    path.join(inputDir, 'readme.md'),\n  ];\n\n  if (!isChildPath(inputDir, docsPath)) {\n    throw new NotAllowedError(\n      `Target path ${docsPath} is not allowed to refer to a location outside ${inputDir}`,\n    );\n  }\n  await fs.ensureDir(docsPath);\n  for (const filePath of fallbacks) {\n    if (!isChildPath(inputDir, filePath)) {\n      throw new NotAllowedError(\n        `Source path ${filePath} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n    try {\n      await fs.copyFile(filePath, indexMdPath);\n      return;\n    } catch (error) {\n      logger.warn(`${path.relative(inputDir, filePath)} not found.`);\n    }\n  }\n\n  logger.warn(\n    `Could not find any techdocs' index file. Please make sure at least one of ${[\n      indexMdPath,\n      ...fallbacks,\n    ].join(' ')} exists.`,\n  );\n};\n\n/**\n * Create or update the techdocs_metadata.json. Values initialized/updated are:\n * - The build_timestamp (now)\n * - The list of files generated\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n */\nexport const createOrUpdateMetadata = async (\n  techdocsMetadataPath: string,\n  logger: LoggerService,\n): Promise<void> => {\n  const techdocsMetadataDir = techdocsMetadataPath\n    .split(path.sep)\n    .slice(0, -1)\n    .join(path.sep);\n  // check if file exists, create if it does not.\n  try {\n    await fs.access(techdocsMetadataPath, fs.constants.F_OK);\n  } catch (err) {\n    // Bootstrap file with empty JSON\n    await fs.writeJson(techdocsMetadataPath, JSON.parse('{}'));\n  }\n  // check if valid Json\n  let json;\n  try {\n    json = await fs.readJson(techdocsMetadataPath);\n  } catch (err) {\n    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${\n      toError(err).message\n    }`;\n    logger.error(message);\n    throw new Error(message);\n  }\n\n  json.build_timestamp = Date.now();\n\n  // Get and write generated files to the metadata JSON. Each file string is in\n  // a form appropriate for invalidating the associated object from cache.\n  try {\n    json.files = (await getFileTreeRecursively(techdocsMetadataDir)).map(file =>\n      file.replace(`${techdocsMetadataDir}${path.sep}`, ''),\n    );\n  } catch (err) {\n    json.files = [];\n    logger.warn(\n      `Unable to add files list to metadata: ${toError(err).message}`,\n    );\n  }\n\n  await fs.writeJson(techdocsMetadataPath, json);\n  return;\n};\n\n/**\n * Update the techdocs_metadata.json to add etag of the prepared tree (e.g. commit SHA or actual Etag of the resource).\n * This is helpful to check if a TechDocs site in storage has gone outdated, without maintaining an in-memory build info\n * per Backstage instance.\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n * @param etag - The ETag to use\n */\nexport const storeEtagMetadata = async (\n  techdocsMetadataPath: string,\n  etag: string,\n): Promise<void> => {\n  const json = await fs.readJson(techdocsMetadataPath);\n  json.etag = etag;\n  await fs.writeJson(techdocsMetadataPath, json);\n};\n"],"names":["PassThrough","spawn","gitUrlParse","DEFAULT_SCHEMA","Type","path","fs","yaml","ForwardedError","isChildPath","resolvePath","NotAllowedError","toError","getFileTreeRecursively"],"mappings":"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"}

package/dist/stages/generate/index.cjs.js

@@ -1,9 +1,9 @@
 'use strict';
 
+require('fs-extra');
 require('node:path');
 require('@backstage/integration');
 var helpers = require('./helpers.cjs.js');
-require('fs-extra');
 require('js-yaml');
 require('@backstage/errors');
 require('./DockerContainerRunner.cjs.js');

package/dist/stages/generate/mkdocsPatchers.cjs.js

@@ -11,6 +11,10 @@ var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
 var yaml__default = /*#__PURE__*/_interopDefaultCompat(yaml);
 
 const MATERIAL_THEME = "material";
+const PYMDOWNX_SNIPPETS_EXTENSION = "pymdownx.snippets";
+function isPymdownxSnippetsExtension(extensionName) {
+  return extensionName === PYMDOWNX_SNIPPETS_EXTENSION || extensionName === `${PYMDOWNX_SNIPPETS_EXTENSION}:SnippetExtension`;
+}
 function isThemeObject(theme) {
   return typeof theme === "object" && theme !== null && !Array.isArray(theme);
 }
@@ -142,10 +146,80 @@ const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys) =
         sanitized[key] = mkdocsYml[key];
       }
     }
+    const extensions = sanitized.markdown_extensions;
+    if (Array.isArray(extensions)) {
+      const removedEntries = [];
+      sanitized.markdown_extensions = extensions.filter((ext) => {
+        if (typeof ext === "string") {
+          if (isPymdownxSnippetsExtension(ext)) {
+            return true;
+          }
+          if (ext.includes(":")) {
+            removedEntries.push(ext);
+            return false;
+          }
+          return true;
+        }
+        if (!ext || typeof ext !== "object" || Array.isArray(ext)) {
+          return true;
+        }
+        const extensionEntries = Object.entries(ext);
+        const dangerousNames = extensionEntries.map(([extensionName]) => extensionName).filter(
+          (extensionName) => extensionName.includes(":") && !isPymdownxSnippetsExtension(extensionName)
+        );
+        if (dangerousNames.length > 0) {
+          removedEntries.push(...dangerousNames);
+          return false;
+        }
+        for (const [extensionName, extensionConfig] of extensionEntries) {
+          if (!isPymdownxSnippetsExtension(extensionName)) {
+            continue;
+          }
+          if (extensionConfig !== null && (typeof extensionConfig !== "object" || Object.keys(extensionConfig).length > 0)) {
+            removedEntries.push(`${extensionName} configuration`);
+          }
+          Object.assign(ext, { [extensionName]: {} });
+        }
+        for (const extConfig of Object.values(ext)) {
+          if (extConfig && typeof extConfig === "object" && !Array.isArray(extConfig)) {
+            for (const dangerousKey of helpers.DANGEROUS_EXTENSION_CONFIG_KEYS) {
+              if (dangerousKey in extConfig) {
+                delete extConfig[dangerousKey];
+                removedEntries.push(dangerousKey);
+              }
+            }
+          }
+        }
+        return true;
+      });
+      if (removedEntries.length > 0) {
+        logger.warn(
+          `Removed the following dangerous entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(
+            ", "
+          )}.`
+        );
+      }
+    }
     for (const key of Object.keys(mkdocsYml)) {
       delete mkdocsYml[key];
     }
     Object.assign(mkdocsYml, sanitized);
+    const theme = mkdocsYml.theme;
+    if (isThemeObject(theme)) {
+      const removedThemeKeys = Object.keys(theme).filter(
+        (key) => !helpers.ALLOWED_THEME_KEYS.has(key)
+      );
+      if (removedThemeKeys.length > 0) {
+        for (const key of removedThemeKeys) {
+          delete theme[key];
+        }
+        logger.warn(
+          `Removed the following unsupported keys from theme configuration in mkdocs.yml: ${removedThemeKeys.join(
+            ", "
+          )}.`
+        );
+      }
+    }
     return true;
   });
 };

package/dist/stages/generate/mkdocsPatchers.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"mkdocsPatchers.cjs.js","sources":["../../../src/stages/generate/mkdocsPatchers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fs from 'fs-extra';\nimport yaml from 'js-yaml';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport {\n  ALLOWED_MKDOCS_KEYS,\n  getRepoUrlFromLocationAnnotation,\n  MKDOCS_SCHEMA,\n} from './helpers';\nimport { toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { LoggerService } from '@backstage/backend-plugin-api';\n\nconst MATERIAL_THEME = 'material';\n\ntype MkDocsThemeObject = {\n  name?: string;\n  font?: boolean;\n};\n\nfunction isThemeObject(theme: unknown): theme is MkDocsThemeObject {\n  return typeof theme === 'object' && theme !== null && !Array.isArray(theme);\n}\n\ntype MkDocsObject = {\n  plugins?: string[];\n  docs_dir: string;\n  repo_url?: string;\n  edit_uri?: string;\n  theme?: MkDocsThemeObject;\n};\n\nconst patchMkdocsFile = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  updateAction: (mkdocsYml: MkDocsObject) => boolean,\n) => {\n  // We only want to override the mkdocs.yml if it has actually changed. This is relevant if\n  // used with a 'dir' location on the file system as this would permanently update the file.\n  let didEdit = false;\n\n  let mkdocsYmlFileString;\n  try {\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    logger.warn(\n      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n\n  let mkdocsYml: any;\n  try {\n    mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });\n\n    // mkdocsYml should be an object type after successful parsing.\n    // But based on its type definition, it can also be a string or undefined, which we don't want.\n    if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {\n      throw new Error('Bad YAML format.');\n    }\n  } catch (error) {\n    logger.warn(\n      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n\n  didEdit = updateAction(mkdocsYml);\n\n  try {\n    if (didEdit) {\n      await fs.writeFile(\n        mkdocsYmlPath,\n        yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),\n        'utf8',\n      );\n    }\n  } catch (error) {\n    logger.warn(\n      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add repo_url or edit_uri if it does not exists\n * If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.\n * If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get\n * the repository URL.\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n */\nexport const patchMkdocsYmlPreBuild = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    if (!('repo_url' in mkdocsYml) || !('edit_uri' in mkdocsYml)) {\n      // Add edit_uri and/or repo_url to mkdocs.yml if it is missing.\n      // This will enable the Page edit button generated by MkDocs.\n      // If the either has been set, keep the original value\n      const result = getRepoUrlFromLocationAnnotation(\n        parsedLocationAnnotation,\n        scmIntegrations,\n        mkdocsYml.docs_dir,\n      );\n\n      if (result.repo_url || result.edit_uri) {\n        mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;\n        mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;\n\n        logger.info(\n          `Set ${JSON.stringify(\n            result,\n          )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,\n        );\n        return true;\n      }\n    }\n    return false;\n  });\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add all provided default plugins\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param defaultPlugins - List of default mkdocs plugins\n */\nexport const patchMkdocsYmlWithPlugins = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  defaultPlugins: string[] = ['techdocs-core'],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Modify mkdocs.yaml to contain the required default plugins.\n    // If no plugins are defined we can just return the defaults.\n    if (!('plugins' in mkdocsYml)) {\n      mkdocsYml.plugins = defaultPlugins;\n      return true;\n    }\n\n    // Otherwise, check each default plugin and include it if necessary.\n    let changesMade = false;\n\n    defaultPlugins.forEach(dp => {\n      // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)\n      // then we need to add it\n      if (\n        !(\n          mkdocsYml.plugins!.includes(dp) ||\n          mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))\n        )\n      ) {\n        mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];\n        changesMade = true;\n      }\n    });\n\n    return changesMade;\n  });\n};\n\n/**\n * Disable external font download for the material theme.\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger\n */\nexport const patchMkdocsYmlWithFontDisabled = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    if (!('theme' in mkdocsYml)) {\n      // No theme section exists, create it with font disabled\n      mkdocsYml.theme = {\n        name: MATERIAL_THEME,\n        font: false,\n      };\n      return true;\n    }\n\n    const theme = mkdocsYml.theme;\n    if (isThemeObject(theme)) {\n      // Theme section exists. Only modify it when the configured theme is Material\n      if (theme.name === MATERIAL_THEME && !('font' in theme)) {\n        theme.font = false;\n        return true;\n      }\n      if (theme.name !== MATERIAL_THEME) {\n        logger.debug(\n          'mkdocs.yml theme is not \"material\"; skipping font disabling patch',\n        );\n      }\n    }\n\n    return false;\n  });\n};\n\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n */\nexport const sanitizeMkdocsYml = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  additionalAllowedKeys?: string[],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Combine default allowed keys with additional keys\n    const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n    if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n      logger.warn(\n        `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n          ', ',\n        )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n      );\n      additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n    }\n\n    // Identify keys that will be removed for logging\n    const removedKeys = Object.keys(mkdocsYml).filter(\n      key => !allowedKeys.has(key),\n    );\n\n    if (removedKeys.length > 0) {\n      logger.warn(\n        `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n          ', ',\n        )}. ` +\n          `TechDocs only supports a subset of MkDocs configuration options.`,\n      );\n    }\n\n    // Build a new object with only allowed keys\n    const sanitized: Record<string, unknown> = {};\n    for (const key of allowedKeys) {\n      if (key in mkdocsYml) {\n        sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n      }\n    }\n\n    // Clear the original object and copy sanitized values back\n    for (const key of Object.keys(mkdocsYml)) {\n      delete (mkdocsYml as Record<string, unknown>)[key];\n    }\n    Object.assign(mkdocsYml, sanitized);\n\n    // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n    return true;\n  });\n};\n"],"names":["fs","toError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS"],"mappings":"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"}
+{"version":3,"file":"mkdocsPatchers.cjs.js","sources":["../../../src/stages/generate/mkdocsPatchers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fs from 'fs-extra';\nimport yaml from 'js-yaml';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport {\n  ALLOWED_MKDOCS_KEYS,\n  ALLOWED_THEME_KEYS,\n  DANGEROUS_EXTENSION_CONFIG_KEYS,\n  getRepoUrlFromLocationAnnotation,\n  MKDOCS_SCHEMA,\n} from './helpers';\nimport { toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { LoggerService } from '@backstage/backend-plugin-api';\n\nconst MATERIAL_THEME = 'material';\nconst PYMDOWNX_SNIPPETS_EXTENSION = 'pymdownx.snippets';\n\nfunction isPymdownxSnippetsExtension(extensionName: string): boolean {\n  return (\n    extensionName === PYMDOWNX_SNIPPETS_EXTENSION ||\n    extensionName === `${PYMDOWNX_SNIPPETS_EXTENSION}:SnippetExtension`\n  );\n}\n\ntype MkDocsThemeObject = {\n  name?: string;\n  font?: boolean;\n};\n\nfunction isThemeObject(theme: unknown): theme is MkDocsThemeObject {\n  return typeof theme === 'object' && theme !== null && !Array.isArray(theme);\n}\n\ntype MkDocsObject = {\n  plugins?: string[];\n  docs_dir: string;\n  repo_url?: string;\n  edit_uri?: string;\n  theme?: MkDocsThemeObject;\n};\n\nconst patchMkdocsFile = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  updateAction: (mkdocsYml: MkDocsObject) => boolean,\n) => {\n  // We only want to override the mkdocs.yml if it has actually changed. This is relevant if\n  // used with a 'dir' location on the file system as this would permanently update the file.\n  let didEdit = false;\n\n  let mkdocsYmlFileString;\n  try {\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    logger.warn(\n      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n\n  let mkdocsYml: any;\n  try {\n    mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });\n\n    // mkdocsYml should be an object type after successful parsing.\n    // But based on its type definition, it can also be a string or undefined, which we don't want.\n    if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {\n      throw new Error('Bad YAML format.');\n    }\n  } catch (error) {\n    logger.warn(\n      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n\n  didEdit = updateAction(mkdocsYml);\n\n  try {\n    if (didEdit) {\n      await fs.writeFile(\n        mkdocsYmlPath,\n        yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),\n        'utf8',\n      );\n    }\n  } catch (error) {\n    logger.warn(\n      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${\n        toError(error).message\n      }`,\n    );\n    return;\n  }\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add repo_url or edit_uri if it does not exists\n * If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.\n * If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get\n * the repository URL.\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n */\nexport const patchMkdocsYmlPreBuild = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    if (!('repo_url' in mkdocsYml) || !('edit_uri' in mkdocsYml)) {\n      // Add edit_uri and/or repo_url to mkdocs.yml if it is missing.\n      // This will enable the Page edit button generated by MkDocs.\n      // If the either has been set, keep the original value\n      const result = getRepoUrlFromLocationAnnotation(\n        parsedLocationAnnotation,\n        scmIntegrations,\n        mkdocsYml.docs_dir,\n      );\n\n      if (result.repo_url || result.edit_uri) {\n        mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;\n        mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;\n\n        logger.info(\n          `Set ${JSON.stringify(\n            result,\n          )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,\n        );\n        return true;\n      }\n    }\n    return false;\n  });\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add all provided default plugins\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param defaultPlugins - List of default mkdocs plugins\n */\nexport const patchMkdocsYmlWithPlugins = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  defaultPlugins: string[] = ['techdocs-core'],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Modify mkdocs.yaml to contain the required default plugins.\n    // If no plugins are defined we can just return the defaults.\n    if (!('plugins' in mkdocsYml)) {\n      mkdocsYml.plugins = defaultPlugins;\n      return true;\n    }\n\n    // Otherwise, check each default plugin and include it if necessary.\n    let changesMade = false;\n\n    defaultPlugins.forEach(dp => {\n      // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)\n      // then we need to add it\n      if (\n        !(\n          mkdocsYml.plugins!.includes(dp) ||\n          mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))\n        )\n      ) {\n        mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];\n        changesMade = true;\n      }\n    });\n\n    return changesMade;\n  });\n};\n\n/**\n * Disable external font download for the material theme.\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger\n */\nexport const patchMkdocsYmlWithFontDisabled = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    if (!('theme' in mkdocsYml)) {\n      // No theme section exists, create it with font disabled\n      mkdocsYml.theme = {\n        name: MATERIAL_THEME,\n        font: false,\n      };\n      return true;\n    }\n\n    const theme = mkdocsYml.theme;\n    if (isThemeObject(theme)) {\n      // Theme section exists. Only modify it when the configured theme is Material\n      if (theme.name === MATERIAL_THEME && !('font' in theme)) {\n        theme.font = false;\n        return true;\n      }\n      if (theme.name !== MATERIAL_THEME) {\n        logger.debug(\n          'mkdocs.yml theme is not \"material\"; skipping font disabling patch',\n        );\n      }\n    }\n\n    return false;\n  });\n};\n\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n */\nexport const sanitizeMkdocsYml = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  additionalAllowedKeys?: string[],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Combine default allowed keys with additional keys\n    const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n    if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n      logger.warn(\n        `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n          ', ',\n        )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n      );\n      additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n    }\n\n    // Identify keys that will be removed for logging\n    const removedKeys = Object.keys(mkdocsYml).filter(\n      key => !allowedKeys.has(key),\n    );\n\n    if (removedKeys.length > 0) {\n      logger.warn(\n        `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n          ', ',\n        )}. ` +\n          `TechDocs only supports a subset of MkDocs configuration options.`,\n      );\n    }\n\n    // Build a new object with only allowed keys\n    const sanitized: Record<string, unknown> = {};\n    for (const key of allowedKeys) {\n      if (key in mkdocsYml) {\n        sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n      }\n    }\n\n    // Sanitize markdown_extensions\n    const extensions = sanitized.markdown_extensions;\n    if (Array.isArray(extensions)) {\n      const removedEntries: string[] = [];\n\n      sanitized.markdown_extensions = extensions.filter(ext => {\n        if (typeof ext === 'string') {\n          if (isPymdownxSnippetsExtension(ext)) {\n            return true;\n          }\n\n          if (ext.includes(':')) {\n            removedEntries.push(ext);\n            return false;\n          }\n          return true;\n        }\n\n        if (!ext || typeof ext !== 'object' || Array.isArray(ext)) {\n          return true;\n        }\n\n        // Check every key, not just the first, so that a multi-key mapping\n        // cannot smuggle a dangerous name past the filter.\n        const extensionEntries = Object.entries(ext as Record<string, unknown>);\n        const dangerousNames = extensionEntries\n          .map(([extensionName]) => extensionName)\n          .filter(\n            extensionName =>\n              extensionName.includes(':') &&\n              !isPymdownxSnippetsExtension(extensionName),\n          );\n        if (dangerousNames.length > 0) {\n          removedEntries.push(...dangerousNames);\n          return false;\n        }\n\n        for (const [extensionName, extensionConfig] of extensionEntries) {\n          if (!isPymdownxSnippetsExtension(extensionName)) {\n            continue;\n          }\n\n          if (\n            extensionConfig !== null &&\n            (typeof extensionConfig !== 'object' ||\n              Object.keys(extensionConfig).length > 0)\n          ) {\n            removedEntries.push(`${extensionName} configuration`);\n          }\n          Object.assign(ext, { [extensionName]: {} });\n        }\n\n        // Strip dangerous keys from the extension's own configuration.\n        for (const extConfig of Object.values(ext as Record<string, unknown>)) {\n          if (\n            extConfig &&\n            typeof extConfig === 'object' &&\n            !Array.isArray(extConfig)\n          ) {\n            for (const dangerousKey of DANGEROUS_EXTENSION_CONFIG_KEYS) {\n              if (dangerousKey in extConfig) {\n                delete (extConfig as Record<string, unknown>)[dangerousKey];\n                removedEntries.push(dangerousKey);\n              }\n            }\n          }\n        }\n\n        return true;\n      });\n\n      if (removedEntries.length > 0) {\n        logger.warn(\n          `Removed the following dangerous entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(\n            ', ',\n          )}.`,\n        );\n      }\n    }\n\n    // Clear the original object and copy sanitized values back\n    for (const key of Object.keys(mkdocsYml)) {\n      delete (mkdocsYml as Record<string, unknown>)[key];\n    }\n    Object.assign(mkdocsYml, sanitized);\n\n    // Sanitize theme sub-keys\n    const theme = (mkdocsYml as Record<string, unknown>).theme;\n    if (isThemeObject(theme)) {\n      const removedThemeKeys = Object.keys(theme).filter(\n        key => !ALLOWED_THEME_KEYS.has(key),\n      );\n      if (removedThemeKeys.length > 0) {\n        for (const key of removedThemeKeys) {\n          delete (theme as Record<string, unknown>)[key];\n        }\n        logger.warn(\n          `Removed the following unsupported keys from theme configuration in mkdocs.yml: ${removedThemeKeys.join(\n            ', ',\n          )}.`,\n        );\n      }\n    }\n\n    // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n    return true;\n  });\n};\n"],"names":["fs","toError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS","DANGEROUS_EXTENSION_CONFIG_KEYS","ALLOWED_THEME_KEYS"],"mappings":"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"}

package/dist/stages/generate/techdocs.cjs.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var fs = require('fs-extra');
 var path = require('node:path');
 var integration = require('@backstage/integration');
 var helpers = require('./helpers.cjs.js');
@@ -9,6 +10,7 @@ var DockerContainerRunner = require('./DockerContainerRunner.cjs.js');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
 
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
 var path__default = /*#__PURE__*/_interopDefaultCompat(path);
 
 class TechdocsGenerator {
@@ -60,6 +62,14 @@ class TechdocsGenerator {
       inputDir,
       siteOptions
     );
+    const alternateConfigName = path__default.default.basename(mkdocsYmlPath) === "mkdocs.yaml" ? "mkdocs.yml" : "mkdocs.yaml";
+    if (await fs__default.default.pathExists(path__default.default.join(inputDir, alternateConfigName))) {
+      childLogger.warn(
+        `Both mkdocs.yml and mkdocs.yaml found in ${inputDir}; using ${path__default.default.basename(
+          mkdocsYmlPath
+        )}. The other file will be ignored.`
+      );
+    }
     const docsDir = await helpers.validateMkdocsYaml(inputDir, content);
     await mkdocsPatchers.sanitizeMkdocsYml(
       mkdocsYmlPath,
@@ -77,8 +87,7 @@ class TechdocsGenerator {
     if (this.options.legacyCopyReadmeMdToIndexMd) {
       await helpers.patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });
     }
-    const resolvedDocsDir = path__default.default.join(inputDir, docsDir ?? "docs");
-    await helpers.validateDocsDirectory(resolvedDocsDir, inputDir);
+    await helpers.validateInputDirectory(inputDir);
     const defaultPlugins = this.options.defaultPlugins ?? [];
     if (!this.options.omitTechdocsCoreMkdocsPlugin && !defaultPlugins.includes("techdocs-core")) {
       defaultPlugins.push("techdocs-core");
@@ -96,7 +105,7 @@ class TechdocsGenerator {
         case "local":
           await helpers.runCommand({
             command: "mkdocs",
-            args: ["build", "-d", outputDir, "-v"],
+            args: ["build", "-f", mkdocsYmlPath, "-d", outputDir, "-v"],
             options: {
               cwd: inputDir
             },
@@ -110,7 +119,13 @@ class TechdocsGenerator {
           const containerRunner = this.containerRunner || new DockerContainerRunner.DockerContainerRunner();
           await containerRunner.runContainer({
             imageName: this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,
-            args: ["build", "-d", "/output"],
+            args: [
+              "build",
+              "-f",
+              `/input/${path__default.default.basename(mkdocsYmlPath)}`,
+              "-d",
+              "/output"
+            ],
             logStream,
             mountDirs,
             workingDir: "/input",

package/dist/stages/generate/techdocs.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"techdocs.cjs.js","sources":["../../../src/stages/generate/techdocs.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport path from 'node:path';\nimport {\n  ScmIntegrationRegistry,\n  ScmIntegrations,\n} from '@backstage/integration';\nimport {\n  createOrUpdateMetadata,\n  getMkdocsYml,\n  patchIndexPreBuild,\n  runCommand,\n  storeEtagMetadata,\n  validateDocsDirectory,\n  validateMkdocsYaml,\n} from './helpers';\n\nimport {\n  patchMkdocsYmlPreBuild,\n  patchMkdocsYmlWithFontDisabled,\n  patchMkdocsYmlWithPlugins,\n  sanitizeMkdocsYml,\n} from './mkdocsPatchers';\nimport {\n  GeneratorBase,\n  GeneratorConfig,\n  GeneratorOptions,\n  GeneratorRunInType,\n  GeneratorRunOptions,\n} from './types';\nimport { ForwardedError } from '@backstage/errors';\nimport { DockerContainerRunner } from './DockerContainerRunner';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Generates documentation files\n * @public\n */\nexport class TechdocsGenerator implements GeneratorBase {\n  /**\n   * The default docker image (and version) used to generate content. Public\n   * and static so that techdocs-node consumers can use the same version.\n   *\n   * See {@link https://hub.docker.com/r/spotify/techdocs/tags} for list of available versions.\n   */\n  public static readonly defaultDockerImage = 'spotify/techdocs:v1.2.8';\n  private readonly logger: LoggerService;\n  private readonly containerRunner?: TechDocsContainerRunner;\n  private readonly options: GeneratorConfig;\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n\n  /**\n   * Returns a instance of TechDocs generator\n   * @param config - A Backstage configuration\n   * @param options - Options to configure the generator\n   */\n  static fromConfig(config: Config, options: GeneratorOptions) {\n    const { containerRunner, logger } = options;\n    const scmIntegrations = ScmIntegrations.fromConfig(config);\n    return new TechdocsGenerator({\n      logger,\n      containerRunner,\n      config,\n      scmIntegrations,\n    });\n  }\n\n  constructor(options: {\n    logger: LoggerService;\n    containerRunner?: TechDocsContainerRunner;\n    config: Config;\n    scmIntegrations: ScmIntegrationRegistry;\n  }) {\n    this.logger = options.logger;\n    this.options = readGeneratorConfig(options.config, options.logger);\n    this.containerRunner = options.containerRunner;\n    this.scmIntegrations = options.scmIntegrations;\n  }\n\n  /** {@inheritDoc GeneratorBase.run} */\n  public async run(options: GeneratorRunOptions): Promise<void> {\n    const {\n      inputDir,\n      outputDir,\n      parsedLocationAnnotation,\n      etag,\n      logger: childLogger,\n      logStream,\n      siteOptions,\n      runAsDefaultUser,\n    } = options;\n\n    // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url\n    const { path: mkdocsYmlPath, content } = await getMkdocsYml(\n      inputDir,\n      siteOptions,\n    );\n\n    // validate the docs_dir first\n    const docsDir = await validateMkdocsYaml(inputDir, content);\n\n    // Remove unsupported configuration keys\n    await sanitizeMkdocsYml(\n      mkdocsYmlPath,\n      childLogger,\n      this.options.dangerouslyAllowAdditionalKeys,\n    );\n\n    if (parsedLocationAnnotation) {\n      await patchMkdocsYmlPreBuild(\n        mkdocsYmlPath,\n        childLogger,\n        parsedLocationAnnotation,\n        this.scmIntegrations,\n      );\n    }\n\n    if (this.options.legacyCopyReadmeMdToIndexMd) {\n      await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });\n    }\n\n    // Validate that no symlinks in the docs directory point outside the input directory\n    // This prevents path traversal attacks where malicious symlinks could leak host files\n    const resolvedDocsDir = path.join(inputDir, docsDir ?? 'docs');\n\n    await validateDocsDirectory(resolvedDocsDir, inputDir);\n\n    // patch the list of mkdocs plugins\n    const defaultPlugins = this.options.defaultPlugins ?? [];\n\n    if (\n      !this.options.omitTechdocsCoreMkdocsPlugin &&\n      !defaultPlugins.includes('techdocs-core')\n    ) {\n      defaultPlugins.push('techdocs-core');\n    }\n\n    await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);\n    if (this.options.disableExternalFonts) {\n      await patchMkdocsYmlWithFontDisabled(mkdocsYmlPath, childLogger);\n    }\n\n    // Directories to bind on container\n    const mountDirs = {\n      [inputDir]: '/input',\n      [outputDir]: '/output',\n    };\n\n    try {\n      switch (this.options.runIn) {\n        case 'local':\n          await runCommand({\n            command: 'mkdocs',\n            args: ['build', '-d', outputDir, '-v'],\n            options: {\n              cwd: inputDir,\n            },\n            logStream,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,\n          );\n          break;\n        case 'docker': {\n          const containerRunner =\n            this.containerRunner || new DockerContainerRunner();\n          await containerRunner.runContainer({\n            imageName:\n              this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,\n            args: ['build', '-d', '/output'],\n            logStream,\n            mountDirs,\n            workingDir: '/input',\n            // Set the home directory inside the container as something that applications can\n            // write to, otherwise they will just fail trying to write to /\n            envVars: { HOME: '/tmp' },\n            pullImage: this.options.pullImage,\n            defaultUser: runAsDefaultUser,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,\n          );\n          break;\n        }\n        default:\n          throw new Error(\n            `Invalid config value \"${this.options.runIn}\" provided in 'techdocs.generators.techdocs'.`,\n          );\n      }\n    } catch (error) {\n      this.logger.debug(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n      );\n      throw new ForwardedError(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n        error,\n      );\n    }\n\n    /**\n     * Post Generate steps\n     */\n\n    // Add build timestamp and files to techdocs_metadata.json\n    // Creates techdocs_metadata.json if file does not exist.\n    await createOrUpdateMetadata(\n      path.join(outputDir, 'techdocs_metadata.json'),\n      childLogger,\n    );\n\n    // Add etag of the prepared tree to techdocs_metadata.json\n    // Assumes that the file already exists.\n    if (etag) {\n      await storeEtagMetadata(\n        path.join(outputDir, 'techdocs_metadata.json'),\n        etag,\n      );\n    }\n  }\n}\n\nexport function readGeneratorConfig(\n  config: Config,\n  logger: LoggerService,\n): GeneratorConfig {\n  const legacyGeneratorType = config.getOptionalString(\n    'techdocs.generators.techdocs',\n  ) as GeneratorRunInType;\n\n  if (legacyGeneratorType) {\n    logger.warn(\n      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +\n        `See here https://backstage.io/docs/features/techdocs/configuration`,\n    );\n  }\n\n  return {\n    runIn:\n      legacyGeneratorType ??\n      config.getOptionalString('techdocs.generator.runIn') ??\n      'docker',\n    dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),\n    pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),\n    omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.omitTechdocsCorePlugin',\n    ),\n    legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',\n    ),\n    defaultPlugins: config.getOptionalStringArray(\n      'techdocs.generator.mkdocs.defaultPlugins',\n    ),\n    dangerouslyAllowAdditionalKeys: config.getOptionalStringArray(\n      'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys',\n    ),\n    disableExternalFonts: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.disableExternalFonts',\n    ),\n  };\n}\n"],"names":["ScmIntegrations","getMkdocsYml","validateMkdocsYaml","sanitizeMkdocsYml","patchMkdocsYmlPreBuild","patchIndexPreBuild","path","validateDocsDirectory","patchMkdocsYmlWithPlugins","patchMkdocsYmlWithFontDisabled","runCommand","DockerContainerRunner","ForwardedError","createOrUpdateMetadata","storeEtagMetadata"],"mappings":"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"}
+{"version":3,"file":"techdocs.cjs.js","sources":["../../../src/stages/generate/techdocs.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport fs from 'fs-extra';\nimport path from 'node:path';\nimport {\n  ScmIntegrationRegistry,\n  ScmIntegrations,\n} from '@backstage/integration';\nimport {\n  createOrUpdateMetadata,\n  getMkdocsYml,\n  patchIndexPreBuild,\n  runCommand,\n  storeEtagMetadata,\n  validateInputDirectory,\n  validateMkdocsYaml,\n} from './helpers';\n\nimport {\n  patchMkdocsYmlPreBuild,\n  patchMkdocsYmlWithFontDisabled,\n  patchMkdocsYmlWithPlugins,\n  sanitizeMkdocsYml,\n} from './mkdocsPatchers';\nimport {\n  GeneratorBase,\n  GeneratorConfig,\n  GeneratorOptions,\n  GeneratorRunInType,\n  GeneratorRunOptions,\n} from './types';\nimport { ForwardedError } from '@backstage/errors';\nimport { DockerContainerRunner } from './DockerContainerRunner';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Generates documentation files\n * @public\n */\nexport class TechdocsGenerator implements GeneratorBase {\n  /**\n   * The default docker image (and version) used to generate content. Public\n   * and static so that techdocs-node consumers can use the same version.\n   *\n   * See {@link https://hub.docker.com/r/spotify/techdocs/tags} for list of available versions.\n   */\n  public static readonly defaultDockerImage = 'spotify/techdocs:v1.2.8';\n  private readonly logger: LoggerService;\n  private readonly containerRunner?: TechDocsContainerRunner;\n  private readonly options: GeneratorConfig;\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n\n  /**\n   * Returns a instance of TechDocs generator\n   * @param config - A Backstage configuration\n   * @param options - Options to configure the generator\n   */\n  static fromConfig(config: Config, options: GeneratorOptions) {\n    const { containerRunner, logger } = options;\n    const scmIntegrations = ScmIntegrations.fromConfig(config);\n    return new TechdocsGenerator({\n      logger,\n      containerRunner,\n      config,\n      scmIntegrations,\n    });\n  }\n\n  constructor(options: {\n    logger: LoggerService;\n    containerRunner?: TechDocsContainerRunner;\n    config: Config;\n    scmIntegrations: ScmIntegrationRegistry;\n  }) {\n    this.logger = options.logger;\n    this.options = readGeneratorConfig(options.config, options.logger);\n    this.containerRunner = options.containerRunner;\n    this.scmIntegrations = options.scmIntegrations;\n  }\n\n  /** {@inheritDoc GeneratorBase.run} */\n  public async run(options: GeneratorRunOptions): Promise<void> {\n    const {\n      inputDir,\n      outputDir,\n      parsedLocationAnnotation,\n      etag,\n      logger: childLogger,\n      logStream,\n      siteOptions,\n      runAsDefaultUser,\n    } = options;\n\n    // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url\n    const { path: mkdocsYmlPath, content } = await getMkdocsYml(\n      inputDir,\n      siteOptions,\n    );\n\n    // Warn if both config files exist — MkDocs and Backstage resolve them in\n    // different order, so a second file would be silently ignored by one side.\n    const alternateConfigName =\n      path.basename(mkdocsYmlPath) === 'mkdocs.yaml'\n        ? 'mkdocs.yml'\n        : 'mkdocs.yaml';\n    if (await fs.pathExists(path.join(inputDir, alternateConfigName))) {\n      childLogger.warn(\n        `Both mkdocs.yml and mkdocs.yaml found in ${inputDir}; using ${path.basename(\n          mkdocsYmlPath,\n        )}. The other file will be ignored.`,\n      );\n    }\n\n    // validate the docs_dir first\n    const docsDir = await validateMkdocsYaml(inputDir, content);\n\n    // Remove unsupported configuration keys\n    await sanitizeMkdocsYml(\n      mkdocsYmlPath,\n      childLogger,\n      this.options.dangerouslyAllowAdditionalKeys,\n    );\n\n    if (parsedLocationAnnotation) {\n      await patchMkdocsYmlPreBuild(\n        mkdocsYmlPath,\n        childLogger,\n        parsedLocationAnnotation,\n        this.scmIntegrations,\n      );\n    }\n\n    if (this.options.legacyCopyReadmeMdToIndexMd) {\n      await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });\n    }\n\n    // Validate that no symlinks in the input directory point outside it. MkDocs\n    // extensions can access files throughout the input directory, not just docs_dir.\n    await validateInputDirectory(inputDir);\n\n    // patch the list of mkdocs plugins\n    const defaultPlugins = this.options.defaultPlugins ?? [];\n\n    if (\n      !this.options.omitTechdocsCoreMkdocsPlugin &&\n      !defaultPlugins.includes('techdocs-core')\n    ) {\n      defaultPlugins.push('techdocs-core');\n    }\n\n    await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);\n    if (this.options.disableExternalFonts) {\n      await patchMkdocsYmlWithFontDisabled(mkdocsYmlPath, childLogger);\n    }\n\n    // Directories to bind on container\n    const mountDirs = {\n      [inputDir]: '/input',\n      [outputDir]: '/output',\n    };\n\n    try {\n      switch (this.options.runIn) {\n        case 'local':\n          await runCommand({\n            command: 'mkdocs',\n            args: ['build', '-f', mkdocsYmlPath, '-d', outputDir, '-v'],\n            options: {\n              cwd: inputDir,\n            },\n            logStream,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,\n          );\n          break;\n        case 'docker': {\n          const containerRunner =\n            this.containerRunner || new DockerContainerRunner();\n          await containerRunner.runContainer({\n            imageName:\n              this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,\n            args: [\n              'build',\n              '-f',\n              `/input/${path.basename(mkdocsYmlPath)}`,\n              '-d',\n              '/output',\n            ],\n            logStream,\n            mountDirs,\n            workingDir: '/input',\n            // Set the home directory inside the container as something that applications can\n            // write to, otherwise they will just fail trying to write to /\n            envVars: { HOME: '/tmp' },\n            pullImage: this.options.pullImage,\n            defaultUser: runAsDefaultUser,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,\n          );\n          break;\n        }\n        default:\n          throw new Error(\n            `Invalid config value \"${this.options.runIn}\" provided in 'techdocs.generators.techdocs'.`,\n          );\n      }\n    } catch (error) {\n      this.logger.debug(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n      );\n      throw new ForwardedError(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n        error,\n      );\n    }\n\n    /**\n     * Post Generate steps\n     */\n\n    // Add build timestamp and files to techdocs_metadata.json\n    // Creates techdocs_metadata.json if file does not exist.\n    await createOrUpdateMetadata(\n      path.join(outputDir, 'techdocs_metadata.json'),\n      childLogger,\n    );\n\n    // Add etag of the prepared tree to techdocs_metadata.json\n    // Assumes that the file already exists.\n    if (etag) {\n      await storeEtagMetadata(\n        path.join(outputDir, 'techdocs_metadata.json'),\n        etag,\n      );\n    }\n  }\n}\n\nexport function readGeneratorConfig(\n  config: Config,\n  logger: LoggerService,\n): GeneratorConfig {\n  const legacyGeneratorType = config.getOptionalString(\n    'techdocs.generators.techdocs',\n  ) as GeneratorRunInType;\n\n  if (legacyGeneratorType) {\n    logger.warn(\n      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +\n        `See here https://backstage.io/docs/features/techdocs/configuration`,\n    );\n  }\n\n  return {\n    runIn:\n      legacyGeneratorType ??\n      config.getOptionalString('techdocs.generator.runIn') ??\n      'docker',\n    dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),\n    pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),\n    omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.omitTechdocsCorePlugin',\n    ),\n    legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',\n    ),\n    defaultPlugins: config.getOptionalStringArray(\n      'techdocs.generator.mkdocs.defaultPlugins',\n    ),\n    dangerouslyAllowAdditionalKeys: config.getOptionalStringArray(\n      'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys',\n    ),\n    disableExternalFonts: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.disableExternalFonts',\n    ),\n  };\n}\n"],"names":["ScmIntegrations","getMkdocsYml","path","fs","validateMkdocsYaml","sanitizeMkdocsYml","patchMkdocsYmlPreBuild","patchIndexPreBuild","validateInputDirectory","patchMkdocsYmlWithPlugins","patchMkdocsYmlWithFontDisabled","runCommand","DockerContainerRunner","ForwardedError","createOrUpdateMetadata","storeEtagMetadata"],"mappings":"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"}

package/dist/stages/publish/local.cjs.js

@@ -18,6 +18,22 @@ var os__default = /*#__PURE__*/_interopDefaultCompat(os);
 var createLimiter__default = /*#__PURE__*/_interopDefaultCompat(createLimiter);
 var path__default = /*#__PURE__*/_interopDefaultCompat(path);
 
+async function validateNoExternalSymlinks(dir, root) {
+  const entries = await fs__default.default.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path__default.default.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      if (!backendPluginApi.isChildPath(root, fullPath)) {
+        throw new errors.NotAllowedError(
+          `Symlink at ${fullPath} points outside the output directory`
+        );
+      }
+    }
+    if (entry.isDirectory()) {
+      await validateNoExternalSymlinks(fullPath, root);
+    }
+  }
+}
 class LocalPublish {
   legacyPathCasing;
   logger;
@@ -83,6 +99,7 @@ class LocalPublish {
       fs__default.default.mkdirSync(publishDir, { recursive: true });
     }
     try {
+      await validateNoExternalSymlinks(directory, directory);
       await fs__default.default.copy(directory, publishDir);
       this.logger.info(`Published site stored at ${publishDir}`);
     } catch (error) {

package/dist/stages/publish/local.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"local.cjs.js","sources":["../../../src/stages/publish/local.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DiscoveryService,\n  LoggerService,\n  resolvePackagePath,\n  resolveSafeChildPath,\n} from '@backstage/backend-plugin-api';\nimport {\n  Entity,\n  CompoundEntityRef,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport express from 'express';\nimport fs from 'fs-extra';\nimport os from 'node:os';\nimport createLimiter from 'p-limit';\nimport path from 'node:path';\nimport {\n  PublisherBase,\n  PublishRequest,\n  PublishResponse,\n  ReadinessResponse,\n  TechDocsMetadata,\n} from './types';\nimport {\n  getFileTreeRecursively,\n  getHeadersForFileExtension,\n  lowerCaseEntityTripletInStoragePath,\n} from './helpers';\nimport { ForwardedError } from '@backstage/errors';\n\n/**\n * Local publisher which uses the local filesystem to store the generated static files. It uses by default a\n * directory called \"static\" at the root of techdocs-backend plugin unless a directory has been configured by\n * \"techdocs.publisher.local.publishDirectory\".\n */\nexport class LocalPublish implements PublisherBase {\n  private readonly legacyPathCasing: boolean;\n  private readonly logger: LoggerService;\n  private readonly discovery: DiscoveryService;\n  private readonly staticDocsDir: string;\n\n  constructor(options: {\n    logger: LoggerService;\n    discovery: DiscoveryService;\n    legacyPathCasing: boolean;\n    staticDocsDir: string;\n  }) {\n    this.logger = options.logger;\n    this.discovery = options.discovery;\n    this.legacyPathCasing = options.legacyPathCasing;\n    this.staticDocsDir = options.staticDocsDir;\n  }\n\n  static fromConfig(\n    config: Config,\n    logger: LoggerService,\n    discovery: DiscoveryService,\n  ): PublisherBase {\n    const legacyPathCasing =\n      config.getOptionalBoolean(\n        'techdocs.legacyUseCaseSensitiveTripletPaths',\n      ) || false;\n\n    let staticDocsDir = config.getOptionalString(\n      'techdocs.publisher.local.publishDirectory',\n    );\n    if (!staticDocsDir) {\n      try {\n        staticDocsDir = resolvePackagePath(\n          '@backstage/plugin-techdocs-backend',\n          'static/docs',\n        );\n      } catch (err) {\n        // This will most probably never be used.\n        // The try/catch is introduced so that techdocs-cli can import @backstage/plugin-techdocs-node\n        // on CI/CD without installing techdocs backend plugin.\n        staticDocsDir = os.tmpdir();\n      }\n    }\n\n    return new LocalPublish({\n      logger,\n      discovery,\n      legacyPathCasing,\n      staticDocsDir,\n    });\n  }\n\n  async getReadiness(): Promise<ReadinessResponse> {\n    return {\n      isAvailable: true,\n    };\n  }\n\n  async publish({\n    entity,\n    directory,\n  }: PublishRequest): Promise<PublishResponse> {\n    const entityNamespace = entity.metadata.namespace ?? 'default';\n    let publishDir: string;\n\n    try {\n      publishDir = this.staticEntityPathJoin(\n        entityNamespace,\n        entity.kind,\n        entity.metadata.name,\n      );\n    } catch (error) {\n      throw new ForwardedError(\n        `Unable to publish TechDocs site for entity: ${stringifyEntityRef(\n          entity,\n        )}`,\n        error,\n      );\n    }\n\n    if (!fs.existsSync(publishDir)) {\n      this.logger.info(`Could not find ${publishDir}, creating the directory.`);\n      fs.mkdirSync(publishDir, { recursive: true });\n    }\n\n    try {\n      await fs.copy(directory, publishDir);\n      this.logger.info(`Published site stored at ${publishDir}`);\n    } catch (error) {\n      this.logger.debug(\n        `Failed to copy docs from ${directory} to ${publishDir}`,\n      );\n      throw error;\n    }\n\n    // Generate publish response.\n    const techdocsApiUrl = await this.discovery.getBaseUrl('techdocs');\n    const publishedFilePaths = (await getFileTreeRecursively(publishDir)).map(\n      abs => {\n        return abs.split(`${this.staticDocsDir}/`)[1];\n      },\n    );\n\n    return {\n      remoteUrl: `${techdocsApiUrl}/static/docs/${encodeURIComponent(\n        entity.metadata.name,\n      )}`,\n      objects: publishedFilePaths,\n    };\n  }\n\n  async fetchTechDocsMetadata(\n    entityName: CompoundEntityRef,\n  ): Promise<TechDocsMetadata> {\n    let metadataPath: string;\n\n    try {\n      metadataPath = this.staticEntityPathJoin(\n        entityName.namespace,\n        entityName.kind,\n        entityName.name,\n        'techdocs_metadata.json',\n      );\n    } catch (err) {\n      throw new ForwardedError(\n        `Unexpected entity when fetching metadata: ${stringifyEntityRef(\n          entityName,\n        )}`,\n        err,\n      );\n    }\n\n    try {\n      return await fs.readJson(metadataPath);\n    } catch (err) {\n      throw new ForwardedError(\n        `Unable to read techdocs_metadata.json at ${metadataPath}. Error: ${err}`,\n        err,\n      );\n    }\n  }\n\n  docsRouter(): express.Handler {\n    const router = express.Router();\n\n    // Redirect middleware ensuring that requests to case-sensitive entity\n    // triplet paths are always sent to lower-case versions.\n    router.use((req, res, next) => {\n      // If legacy path casing is on, let the request immediately continue.\n      if (this.legacyPathCasing) {\n        return next();\n      }\n\n      // Generate a lower-case entity triplet path.\n      const [_, namespace, kind, name, ...rest] = req.path.split('/');\n\n      // Ignore non-triplet objects.\n      if (!namespace || !kind || !name) {\n        return next();\n      }\n\n      const newPath = [\n        _,\n        namespace.toLowerCase(),\n        kind.toLowerCase(),\n        name.toLowerCase(),\n        ...rest,\n      ].join('/');\n\n      // If there was no change, then let express.static() handle the request.\n      if (newPath === req.path) {\n        return next();\n      }\n\n      // Otherwise, redirect to the new path.\n      return res.redirect(301, req.baseUrl + newPath);\n    });\n    router.use(\n      express.static(this.staticDocsDir, {\n        // Handle content-type header the same as all other publishers.\n        setHeaders: (res, filePath) => {\n          const fileExtension = path.extname(filePath);\n          const headers = getHeadersForFileExtension(fileExtension);\n          for (const [header, value] of Object.entries(headers)) {\n            res.setHeader(header, value);\n          }\n        },\n      }),\n    );\n\n    return router;\n  }\n\n  async hasDocsBeenGenerated(entity: Entity): Promise<boolean> {\n    const namespace = entity.metadata.namespace ?? 'default';\n\n    // Check if the file exists\n    try {\n      const indexHtmlPath = this.staticEntityPathJoin(\n        namespace,\n        entity.kind,\n        entity.metadata.name,\n        'index.html',\n      );\n\n      await fs.access(indexHtmlPath, fs.constants.F_OK);\n\n      return true;\n    } catch (err) {\n      if (err.name === 'NotAllowedError') {\n        this.logger.error(\n          `Unexpected entity when checking if generated: ${stringifyEntityRef(\n            entity,\n          )}`,\n        );\n      }\n      return false;\n    }\n  }\n\n  /**\n   * This code will never run in practice. It is merely here to illustrate how\n   * to implement this method for other storage providers.\n   */\n  async migrateDocsCase({\n    removeOriginal = false,\n    concurrency = 25,\n  }): Promise<void> {\n    // Iterate through every file in the root of the publisher.\n    const files = await getFileTreeRecursively(this.staticDocsDir);\n    const limit = createLimiter(concurrency);\n\n    await Promise.all(\n      files.map(f =>\n        limit(async file => {\n          const relativeFile = file.replace(\n            `${this.staticDocsDir}${path.sep}`,\n            '',\n          );\n          const newFile = lowerCaseEntityTripletInStoragePath(relativeFile);\n\n          // If all parts are already lowercase, ignore.\n          if (relativeFile === newFile) {\n            return;\n          }\n\n          // Otherwise, copy or move the file.\n          await new Promise<void>(resolve => {\n            const migrate = removeOriginal ? fs.move : fs.copyFile;\n            this.logger.debug(`Migrating ${relativeFile}`);\n            migrate(file, newFile, err => {\n              if (err) {\n                this.logger.warn(\n                  `Unable to migrate ${relativeFile}: ${err.message}`,\n                );\n              }\n              resolve();\n            });\n          });\n        }, f),\n      ),\n    );\n  }\n\n  /**\n   * Utility wrapper around path.join(), used to control legacy case logic.\n   */\n  protected staticEntityPathJoin(...allParts: string[]): string {\n    let staticEntityPath = this.staticDocsDir;\n\n    allParts\n      .map(part => part.split(path.sep))\n      .flat()\n      .forEach((part, index) => {\n        // Respect legacy path casing when operating on namespace, kind, or name.\n        if (index < 3) {\n          staticEntityPath = resolveSafeChildPath(\n            staticEntityPath,\n            this.legacyPathCasing ? part : part.toLowerCase(),\n          );\n          return;\n        }\n\n        // Otherwise, respect the provided case.\n        staticEntityPath = resolveSafeChildPath(staticEntityPath, part);\n      });\n\n    return staticEntityPath;\n  }\n}\n"],"names":["resolvePackagePath","os","ForwardedError","stringifyEntityRef","fs","getFileTreeRecursively","express","path","getHeadersForFileExtension","createLimiter","lowerCaseEntityTripletInStoragePath","resolveSafeChildPath"],"mappings":"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"}
+{"version":3,"file":"local.cjs.js","sources":["../../../src/stages/publish/local.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DiscoveryService,\n  isChildPath,\n  LoggerService,\n  resolvePackagePath,\n  resolveSafeChildPath,\n} from '@backstage/backend-plugin-api';\nimport {\n  Entity,\n  CompoundEntityRef,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport express from 'express';\nimport fs from 'fs-extra';\nimport os from 'node:os';\nimport createLimiter from 'p-limit';\nimport path from 'node:path';\nimport {\n  PublisherBase,\n  PublishRequest,\n  PublishResponse,\n  ReadinessResponse,\n  TechDocsMetadata,\n} from './types';\nimport {\n  getFileTreeRecursively,\n  getHeadersForFileExtension,\n  lowerCaseEntityTripletInStoragePath,\n} from './helpers';\nimport { ForwardedError, NotAllowedError } from '@backstage/errors';\n\nasync function validateNoExternalSymlinks(\n  dir: string,\n  root: string,\n): Promise<void> {\n  const entries = await fs.readdir(dir, { withFileTypes: true });\n  for (const entry of entries) {\n    const fullPath = path.join(dir, entry.name);\n    if (entry.isSymbolicLink()) {\n      if (!isChildPath(root, fullPath)) {\n        throw new NotAllowedError(\n          `Symlink at ${fullPath} points outside the output directory`,\n        );\n      }\n    }\n    if (entry.isDirectory()) {\n      await validateNoExternalSymlinks(fullPath, root);\n    }\n  }\n}\n\n/**\n * Local publisher which uses the local filesystem to store the generated static files. It uses by default a\n * directory called \"static\" at the root of techdocs-backend plugin unless a directory has been configured by\n * \"techdocs.publisher.local.publishDirectory\".\n */\nexport class LocalPublish implements PublisherBase {\n  private readonly legacyPathCasing: boolean;\n  private readonly logger: LoggerService;\n  private readonly discovery: DiscoveryService;\n  private readonly staticDocsDir: string;\n\n  constructor(options: {\n    logger: LoggerService;\n    discovery: DiscoveryService;\n    legacyPathCasing: boolean;\n    staticDocsDir: string;\n  }) {\n    this.logger = options.logger;\n    this.discovery = options.discovery;\n    this.legacyPathCasing = options.legacyPathCasing;\n    this.staticDocsDir = options.staticDocsDir;\n  }\n\n  static fromConfig(\n    config: Config,\n    logger: LoggerService,\n    discovery: DiscoveryService,\n  ): PublisherBase {\n    const legacyPathCasing =\n      config.getOptionalBoolean(\n        'techdocs.legacyUseCaseSensitiveTripletPaths',\n      ) || false;\n\n    let staticDocsDir = config.getOptionalString(\n      'techdocs.publisher.local.publishDirectory',\n    );\n    if (!staticDocsDir) {\n      try {\n        staticDocsDir = resolvePackagePath(\n          '@backstage/plugin-techdocs-backend',\n          'static/docs',\n        );\n      } catch (err) {\n        // This will most probably never be used.\n        // The try/catch is introduced so that techdocs-cli can import @backstage/plugin-techdocs-node\n        // on CI/CD without installing techdocs backend plugin.\n        staticDocsDir = os.tmpdir();\n      }\n    }\n\n    return new LocalPublish({\n      logger,\n      discovery,\n      legacyPathCasing,\n      staticDocsDir,\n    });\n  }\n\n  async getReadiness(): Promise<ReadinessResponse> {\n    return {\n      isAvailable: true,\n    };\n  }\n\n  async publish({\n    entity,\n    directory,\n  }: PublishRequest): Promise<PublishResponse> {\n    const entityNamespace = entity.metadata.namespace ?? 'default';\n    let publishDir: string;\n\n    try {\n      publishDir = this.staticEntityPathJoin(\n        entityNamespace,\n        entity.kind,\n        entity.metadata.name,\n      );\n    } catch (error) {\n      throw new ForwardedError(\n        `Unable to publish TechDocs site for entity: ${stringifyEntityRef(\n          entity,\n        )}`,\n        error,\n      );\n    }\n\n    if (!fs.existsSync(publishDir)) {\n      this.logger.info(`Could not find ${publishDir}, creating the directory.`);\n      fs.mkdirSync(publishDir, { recursive: true });\n    }\n\n    try {\n      await validateNoExternalSymlinks(directory, directory);\n      await fs.copy(directory, publishDir);\n      this.logger.info(`Published site stored at ${publishDir}`);\n    } catch (error) {\n      this.logger.debug(\n        `Failed to copy docs from ${directory} to ${publishDir}`,\n      );\n      throw error;\n    }\n\n    // Generate publish response.\n    const techdocsApiUrl = await this.discovery.getBaseUrl('techdocs');\n    const publishedFilePaths = (await getFileTreeRecursively(publishDir)).map(\n      abs => {\n        return abs.split(`${this.staticDocsDir}/`)[1];\n      },\n    );\n\n    return {\n      remoteUrl: `${techdocsApiUrl}/static/docs/${encodeURIComponent(\n        entity.metadata.name,\n      )}`,\n      objects: publishedFilePaths,\n    };\n  }\n\n  async fetchTechDocsMetadata(\n    entityName: CompoundEntityRef,\n  ): Promise<TechDocsMetadata> {\n    let metadataPath: string;\n\n    try {\n      metadataPath = this.staticEntityPathJoin(\n        entityName.namespace,\n        entityName.kind,\n        entityName.name,\n        'techdocs_metadata.json',\n      );\n    } catch (err) {\n      throw new ForwardedError(\n        `Unexpected entity when fetching metadata: ${stringifyEntityRef(\n          entityName,\n        )}`,\n        err,\n      );\n    }\n\n    try {\n      return await fs.readJson(metadataPath);\n    } catch (err) {\n      throw new ForwardedError(\n        `Unable to read techdocs_metadata.json at ${metadataPath}. Error: ${err}`,\n        err,\n      );\n    }\n  }\n\n  docsRouter(): express.Handler {\n    const router = express.Router();\n\n    // Redirect middleware ensuring that requests to case-sensitive entity\n    // triplet paths are always sent to lower-case versions.\n    router.use((req, res, next) => {\n      // If legacy path casing is on, let the request immediately continue.\n      if (this.legacyPathCasing) {\n        return next();\n      }\n\n      // Generate a lower-case entity triplet path.\n      const [_, namespace, kind, name, ...rest] = req.path.split('/');\n\n      // Ignore non-triplet objects.\n      if (!namespace || !kind || !name) {\n        return next();\n      }\n\n      const newPath = [\n        _,\n        namespace.toLowerCase(),\n        kind.toLowerCase(),\n        name.toLowerCase(),\n        ...rest,\n      ].join('/');\n\n      // If there was no change, then let express.static() handle the request.\n      if (newPath === req.path) {\n        return next();\n      }\n\n      // Otherwise, redirect to the new path.\n      return res.redirect(301, req.baseUrl + newPath);\n    });\n    router.use(\n      express.static(this.staticDocsDir, {\n        // Handle content-type header the same as all other publishers.\n        setHeaders: (res, filePath) => {\n          const fileExtension = path.extname(filePath);\n          const headers = getHeadersForFileExtension(fileExtension);\n          for (const [header, value] of Object.entries(headers)) {\n            res.setHeader(header, value);\n          }\n        },\n      }),\n    );\n\n    return router;\n  }\n\n  async hasDocsBeenGenerated(entity: Entity): Promise<boolean> {\n    const namespace = entity.metadata.namespace ?? 'default';\n\n    // Check if the file exists\n    try {\n      const indexHtmlPath = this.staticEntityPathJoin(\n        namespace,\n        entity.kind,\n        entity.metadata.name,\n        'index.html',\n      );\n\n      await fs.access(indexHtmlPath, fs.constants.F_OK);\n\n      return true;\n    } catch (err) {\n      if (err.name === 'NotAllowedError') {\n        this.logger.error(\n          `Unexpected entity when checking if generated: ${stringifyEntityRef(\n            entity,\n          )}`,\n        );\n      }\n      return false;\n    }\n  }\n\n  /**\n   * This code will never run in practice. It is merely here to illustrate how\n   * to implement this method for other storage providers.\n   */\n  async migrateDocsCase({\n    removeOriginal = false,\n    concurrency = 25,\n  }): Promise<void> {\n    // Iterate through every file in the root of the publisher.\n    const files = await getFileTreeRecursively(this.staticDocsDir);\n    const limit = createLimiter(concurrency);\n\n    await Promise.all(\n      files.map(f =>\n        limit(async file => {\n          const relativeFile = file.replace(\n            `${this.staticDocsDir}${path.sep}`,\n            '',\n          );\n          const newFile = lowerCaseEntityTripletInStoragePath(relativeFile);\n\n          // If all parts are already lowercase, ignore.\n          if (relativeFile === newFile) {\n            return;\n          }\n\n          // Otherwise, copy or move the file.\n          await new Promise<void>(resolve => {\n            const migrate = removeOriginal ? fs.move : fs.copyFile;\n            this.logger.debug(`Migrating ${relativeFile}`);\n            migrate(file, newFile, err => {\n              if (err) {\n                this.logger.warn(\n                  `Unable to migrate ${relativeFile}: ${err.message}`,\n                );\n              }\n              resolve();\n            });\n          });\n        }, f),\n      ),\n    );\n  }\n\n  /**\n   * Utility wrapper around path.join(), used to control legacy case logic.\n   */\n  protected staticEntityPathJoin(...allParts: string[]): string {\n    let staticEntityPath = this.staticDocsDir;\n\n    allParts\n      .map(part => part.split(path.sep))\n      .flat()\n      .forEach((part, index) => {\n        // Respect legacy path casing when operating on namespace, kind, or name.\n        if (index < 3) {\n          staticEntityPath = resolveSafeChildPath(\n            staticEntityPath,\n            this.legacyPathCasing ? part : part.toLowerCase(),\n          );\n          return;\n        }\n\n        // Otherwise, respect the provided case.\n        staticEntityPath = resolveSafeChildPath(staticEntityPath, part);\n      });\n\n    return staticEntityPath;\n  }\n}\n"],"names":["fs","path","isChildPath","NotAllowedError","resolvePackagePath","os","ForwardedError","stringifyEntityRef","getFileTreeRecursively","express","getHeadersForFileExtension","createLimiter","lowerCaseEntityTripletInStoragePath","resolveSafeChildPath"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-node",
-  "version": "0.0.0-nightly-20260818023149",
+  "version": "0.0.0-nightly-20260829022506",
   "description": "Common node.js functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli",
   "backstage": {
     "role": "node-library",
@@ -53,13 +53,13 @@
     "@aws-sdk/types": "^3.347.0",
     "@azure/identity": "^4.0.0",
     "@azure/storage-blob": "^12.5.0",
-    "@backstage/backend-plugin-api": "0.0.0-nightly-20260818023149",
-    "@backstage/catalog-model": "0.0.0-nightly-20260818023149",
+    "@backstage/backend-plugin-api": "1.10.0",
+    "@backstage/catalog-model": "1.10.0",
     "@backstage/config": "1.3.8",
     "@backstage/errors": "1.3.1",
-    "@backstage/integration": "0.0.0-nightly-20260818023149",
-    "@backstage/integration-aws-node": "0.0.0-nightly-20260818023149",
-    "@backstage/plugin-search-common": "0.0.0-nightly-20260818023149",
+    "@backstage/integration": "0.0.0-nightly-20260829022506",
+    "@backstage/integration-aws-node": "0.2.1",
+    "@backstage/plugin-search-common": "1.2.24",
     "@backstage/plugin-techdocs-common": "0.1.1",
     "@google-cloud/storage": "^7.0.0",
     "@smithy/node-http-handler": "^3.0.0",
@@ -78,8 +78,8 @@
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "0.0.0-nightly-20260818023149",
-    "@backstage/cli": "0.0.0-nightly-20260818023149",
+    "@backstage/backend-test-utils": "0.0.0-nightly-20260829022506",
+    "@backstage/cli": "0.0.0-nightly-20260829022506",
     "@types/fs-extra": "^11.0.0",
     "@types/js-yaml": "^4.0.0",
     "@types/mime-types": "^2.1.0",