@backstage/plugin-techdocs-node 2.1.0 → 2.2.0-next.0

package/dist/types/helpers.d-DkvPJaTo.d.ts

@@ -0,0 +1,100 @@
+import { LoggerService } from '@backstage/backend-plugin-api';
+import { SpawnOptionsWithoutStdio } from 'node:child_process';
+import * as yaml from 'js-yaml';
+import { Writable } from 'node:stream';
+
+/** @alpha */
+type RunCommandOptions = {
+    /** command to run */
+    command: string;
+    /** arguments to pass the command */
+    args: string[];
+    /** options to pass to spawn */
+    options: SpawnOptionsWithoutStdio;
+    /** stream to capture stdout and stderr output */
+    logStream?: Writable;
+};
+/**
+ * Run a command in a sub-process, normally a shell command.
+ * @alpha
+ */
+declare const runCommand: ({ command, args, options, logStream, }: RunCommandOptions) => Promise<void>;
+/**
+ * Preserve YAML merge keys and MkDocs-specific tags while inspecting config.
+ *
+ * @alpha
+ */
+declare const MKDOCS_SCHEMA: yaml.Schema;
+/**
+ * Finds and loads the contents of an mkdocs.yml, mkdocs.yaml file, a file
+ * with a specified name or an ad-hoc created file with minimal config.
+ * @public
+ *
+ * @param inputDir - base dir to be searched for either an mkdocs.yml or mkdocs.yaml file.
+ * @param options - name: default mkdocs site_name to be used with a ad hoc file default value is "Documentation Site"
+ *                  mkdocsConfigFileName (optional): a non-default file name to be used as the config
+ */
+declare const getMkdocsYml: (inputDir: string, options?: {
+    name?: string;
+    mkdocsConfigFileName?: string;
+}) => Promise<{
+    path: string;
+    content: string;
+    configIsTemporary: boolean;
+}>;
+/**
+ * Validating mkdocs config file for incorrect/insecure values
+ * Throws on invalid configs
+ *
+ * @param inputDir - base dir to be used as a docs_dir path validity check
+ * @param mkdocsYmlFileString - The string contents of the loaded
+ *   mkdocs.yml or equivalent of a docs site
+ * @returns the parsed docs_dir or undefined
+ * @alpha
+ */
+declare const validateMkdocsYaml: (inputDir: string, mkdocsYmlFileString: string) => Promise<string | undefined>;
+/**
+ * Validates that the input directory doesn't contain symlinks pointing outside
+ * of it. This prevents path traversal attacks where malicious symlinks could be
+ * used to read arbitrary files from the host filesystem.
+ *
+ * The whole input directory is checked rather than only the docs directory,
+ * because MkDocs extensions can read files from anywhere in the input directory.
+ *
+ * @param inputDir - The input directory to validate (absolute path)
+ * @alpha
+ */
+declare const validateInputDirectory: (inputDir: string) => Promise<void>;
+/**
+ * Update docs/index.md file before TechDocs generator uses it to generate docs site,
+ * falling back to docs/README.md or README.md in case a default docs/index.md
+ * is not provided.
+ * @alpha
+ */
+declare const patchIndexPreBuild: ({ inputDir, logger, docsDir, }: {
+    inputDir: string;
+    logger: LoggerService;
+    docsDir?: string;
+}) => Promise<void>;
+/**
+ * Create or update the techdocs_metadata.json. Values initialized/updated are:
+ * - The build_timestamp (now)
+ * - The list of files generated
+ *
+ * @param techdocsMetadataPath - File path to techdocs_metadata.json
+ * @alpha
+ */
+declare const createOrUpdateMetadata: (techdocsMetadataPath: string, logger: LoggerService, engine?: string) => Promise<void>;
+/**
+ * Update the techdocs_metadata.json to add etag of the prepared tree (e.g. commit SHA or actual Etag of the resource).
+ * This is helpful to check if a TechDocs site in storage has gone outdated, without maintaining an in-memory build info
+ * per Backstage instance.
+ *
+ * @param techdocsMetadataPath - File path to techdocs_metadata.json
+ * @param etag - The ETag to use
+ * @alpha
+ */
+declare const storeEtagMetadata: (techdocsMetadataPath: string, etag: string) => Promise<void>;
+
+export { MKDOCS_SCHEMA as M, validateMkdocsYaml as a, createOrUpdateMetadata as c, getMkdocsYml as g, patchIndexPreBuild as p, runCommand as r, storeEtagMetadata as s, validateInputDirectory as v };
+export type { RunCommandOptions as R };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-node",
-  "version": "2.1.0",
+  "version": "2.2.0-next.0",
   "description": "Common node.js functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli",
   "backstage": {
     "role": "node-library",
@@ -14,9 +14,7 @@
     ]
   },
   "publishConfig": {
-    "access": "public",
-    "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts"
+    "access": "public"
   },
   "keywords": [
     "techdocs",
@@ -32,8 +30,31 @@
     "directory": "plugins/techdocs-node"
   },
   "license": "Apache-2.0",
-  "main": "dist/index.cjs.js",
-  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs.js"
+    },
+    "./alpha": {
+      "require": "./dist/alpha.cjs.js",
+      "types": "./dist/alpha.d.ts",
+      "default": "./dist/alpha.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "alpha": [
+        "dist/alpha.d.ts"
+      ],
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
   "files": [
     "dist"
   ],
@@ -53,18 +74,19 @@
     "@aws-sdk/types": "^3.347.0",
     "@azure/identity": "^4.0.0",
     "@azure/storage-blob": "^12.5.0",
-    "@backstage/backend-plugin-api": "^1.11.0",
-    "@backstage/catalog-model": "^1.10.2",
-    "@backstage/config": "^1.3.10",
-    "@backstage/errors": "^1.3.2",
-    "@backstage/integration": "^2.1.3",
-    "@backstage/integration-aws-node": "^0.2.3",
-    "@backstage/plugin-search-common": "^1.2.26",
-    "@backstage/plugin-techdocs-common": "^0.1.2",
+    "@backstage/backend-plugin-api": "1.11.1-next.0",
+    "@backstage/catalog-model": "1.10.2",
+    "@backstage/config": "1.3.10",
+    "@backstage/errors": "1.3.2",
+    "@backstage/integration": "2.1.3",
+    "@backstage/integration-aws-node": "0.2.3",
+    "@backstage/plugin-search-common": "1.2.26",
+    "@backstage/plugin-techdocs-common": "0.1.2",
     "@google-cloud/storage": "^7.0.0",
     "@smithy/node-http-handler": "^3.0.0",
     "@trendyol-js/openstack-swift-sdk": "^0.0.7",
     "@types/express": "^4.17.6",
+    "@types/js-yaml": "^4.0.0",
     "dockerode": "^4.0.0",
     "express": "^4.22.0",
     "fs-extra": "^11.2.0",
@@ -78,20 +100,12 @@
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.11.8",
-    "@backstage/cli": "^0.36.7",
+    "@backstage/backend-test-utils": "1.11.9-next.0",
+    "@backstage/cli": "0.36.8-next.0",
     "@types/fs-extra": "^11.0.0",
-    "@types/js-yaml": "^4.0.0",
     "@types/mime-types": "^2.1.0",
     "@types/recursive-readdir": "^2.2.0",
     "@types/supertest": "^2.0.8",
     "supertest": "^7.0.0"
-  },
-  "typesVersions": {
-    "*": {
-      "package.json": [
-        "package.json"
-      ]
-    }
   }
 }