@bluelibs/runner-dev 6.2.0 → 6.4.0

package/dist/docs/packageDocs.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageDocNotFoundError = exports.RUNNER_FRAMEWORK_COMPLETE_DOC_PATHS = exports.RUNNER_FRAMEWORK_COMPACT_DOC_PATHS = void 0;
+exports.readPackageDoc = readPackageDoc;
+exports.readFirstAvailablePackageDoc = readFirstAvailablePackageDoc;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const path_1 = require("../utils/path");
+exports.RUNNER_FRAMEWORK_COMPACT_DOC_PATHS = [
+    "readmes/COMPACT_GUIDE.md",
+];
+exports.RUNNER_FRAMEWORK_COMPLETE_DOC_PATHS = [
+    "readmes/FULL_GUIDE.md",
+];
+const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i;
+const PACKAGE_DOC_ROOTS_BY_PACKAGE = {
+    "@bluelibs/runner": [
+        ".agents/skills/bluelibs-runner-core/references",
+        "node_modules/@bluelibs/runner",
+    ],
+};
+class PackageDocNotFoundError extends Error {
+    attemptedPaths;
+    constructor(packageName, docPaths, attemptedPaths) {
+        super(`Required package docs for ${packageName} were not found. Tried: ${docPaths.join(", ")}`);
+        this.attemptedPaths = attemptedPaths;
+        this.name = "PackageDocNotFoundError";
+    }
+}
+exports.PackageDocNotFoundError = PackageDocNotFoundError;
+function isMissingFileError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function normalizeDocPath(docPath) {
+    const normalized = node_path_1.default.posix.normalize(docPath.replaceAll("\\", "/"));
+    if (!normalized ||
+        normalized === "." ||
+        normalized.startsWith("../") ||
+        normalized === ".." ||
+        node_path_1.default.posix.isAbsolute(normalized)) {
+        return "README.md";
+    }
+    return normalized;
+}
+function getPackageDocCandidatePaths(root, packageName, normalizedDocPath) {
+    const configuredRoots = PACKAGE_DOC_ROOTS_BY_PACKAGE[packageName];
+    if (configuredRoots?.length) {
+        return configuredRoots.map((configuredRoot) => node_path_1.default.join(root, configuredRoot, normalizedDocPath));
+    }
+    const packageRoot = node_path_1.default.join(root, "node_modules", packageName);
+    return [node_path_1.default.join(packageRoot, normalizedDocPath)];
+}
+async function readPackageDoc(packageName, docPath = "README.md") {
+    if (!PACKAGE_NAME_PATTERN.test(packageName)) {
+        return {
+            packageName,
+            filePath: packageName,
+            content: "",
+        };
+    }
+    const root = process.cwd();
+    const normalizedDocPath = normalizeDocPath(docPath);
+    const candidatePaths = getPackageDocCandidatePaths(root, packageName, normalizedDocPath);
+    let lastTriedPath = candidatePaths[0];
+    for (const candidatePath of candidatePaths) {
+        lastTriedPath = candidatePath;
+        try {
+            const content = await promises_1.default.readFile(candidatePath, "utf8");
+            return {
+                packageName,
+                filePath: (0, path_1.sanitizePath)(candidatePath) ?? candidatePath,
+                content,
+            };
+        }
+        catch (error) {
+            if (!isMissingFileError(error)) {
+                throw error;
+            }
+        }
+    }
+    return {
+        packageName,
+        filePath: (0, path_1.sanitizePath)(lastTriedPath) ?? lastTriedPath,
+        content: "",
+    };
+}
+async function readFirstAvailablePackageDoc(packageName, docPaths) {
+    const attemptedPaths = [];
+    for (const docPath of docPaths) {
+        if (!docPath) {
+            continue;
+        }
+        const doc = await readPackageDoc(packageName, docPath);
+        attemptedPaths.push(doc.filePath);
+        if (doc.content) {
+            return doc;
+        }
+    }
+    throw new PackageDocNotFoundError(packageName, docPaths, attemptedPaths);
+}
+//# sourceMappingURL=packageDocs.js.map

package/dist/docs/packageDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageDocs.js","sourceRoot":"","sources":["../../src/docs/packageDocs.ts"],"names":[],"mappings":"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"}

package/dist/exportDocs.d.ts

@@ -0,0 +1,10 @@
+export type ExportDocsOptions = {
+    output?: string;
+    overwrite?: boolean;
+};
+export type ExportDocsResult = {
+    outputDir: string;
+    entryHtmlPath: string;
+    snapshotPath: string;
+};
+export declare function exportDocs(app: unknown, options?: ExportDocsOptions): Promise<ExportDocsResult>;

package/dist/exportDocs.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportDocs = exportDocs;
+const runner_1 = require("@bluelibs/runner");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const printSchema_1 = require("graphql/utilities/printSchema");
+const docsPayload_1 = require("./resources/docsPayload");
+const graphql_accumulator_resource_1 = require("./resources/graphql-accumulator.resource");
+const Introspector_1 = require("./resources/models/Introspector");
+const docsUiAssets_1 = require("./resources/docsUiAssets");
+function resolveOutputDir(output) {
+    const resolved = output ?? "./runner-dev-catalog";
+    return node_path_1.default.isAbsolute(resolved)
+        ? resolved
+        : node_path_1.default.resolve(process.cwd(), resolved);
+}
+function isDefaultOutputDir(outputDir) {
+    return outputDir === resolveOutputDir("./runner-dev-catalog");
+}
+function isDangerousOutputDir(outputDir) {
+    const cwd = node_path_1.default.resolve(process.cwd());
+    const parentDir = node_path_1.default.resolve(cwd, "..");
+    const homeDir = node_path_1.default.resolve(process.env.HOME || "~");
+    const rootDir = node_path_1.default.parse(outputDir).root;
+    return [cwd, parentDir, homeDir, rootDir].includes(outputDir);
+}
+async function assertOutputDirIsSafe(outputDir, options) {
+    if (isDangerousOutputDir(outputDir)) {
+        throw new Error(`Refusing to export Runner-Dev docs into '${outputDir}' because that path is too broad. Pick a dedicated directory instead.`);
+    }
+    let entries = null;
+    try {
+        entries = await promises_1.default.readdir(outputDir);
+    }
+    catch {
+        return;
+    }
+    if (entries.length === 0) {
+        return;
+    }
+    const canOverwrite = options.overwrite === true || isDefaultOutputDir(outputDir);
+    if (!canOverwrite) {
+        throw new Error(`Refusing to overwrite the non-empty export directory '${outputDir}'. Pass { overwrite: true } or choose a dedicated path.`);
+    }
+}
+async function exportDocs(app, options = {}) {
+    const outputDir = resolveOutputDir(options.output);
+    const entryHtmlPath = node_path_1.default.join(outputDir, "index.html");
+    const snapshotPath = node_path_1.default.join(outputDir, "snapshot.json");
+    const uiAssets = await (0, docsUiAssets_1.resolveDocsBuildAssets)();
+    const dryRuntime = await (0, runner_1.run)(app, {
+        dryRun: true,
+        logs: { printThreshold: null },
+    });
+    try {
+        const store = await dryRuntime.getResourceValue(runner_1.resources.store);
+        const runtime = await dryRuntime.getResourceValue(runner_1.resources.runtime);
+        const introspector = new Introspector_1.Introspector({ store, runtime });
+        const graphqlSdl = (0, printSchema_1.printSchema)((0, graphql_accumulator_resource_1.createRunnerDevGraphqlSchema)());
+        const payload = await (0, docsPayload_1.buildDocsPagePayload)({
+            store,
+            introspector,
+            mode: "catalog",
+            getGraphqlSdl: () => graphqlSdl,
+        });
+        if (!payload.graphqlSdl || payload.graphqlSdl.trim().length === 0) {
+            throw new Error("Runner-Dev export could not generate graphqlSdl for the snapshot payload.");
+        }
+        await assertOutputDirIsSafe(outputDir, options);
+        await promises_1.default.rm(outputDir, { recursive: true, force: true });
+        await promises_1.default.mkdir(node_path_1.default.dirname(outputDir), { recursive: true });
+        await promises_1.default.mkdir(outputDir, { recursive: true });
+        await promises_1.default.writeFile(snapshotPath, JSON.stringify(payload, null, 2), "utf8");
+        await promises_1.default.writeFile(entryHtmlPath, await (0, docsUiAssets_1.renderStandaloneDocsHtml)({
+            uiDir: uiAssets.uiDir,
+            entry: uiAssets.entry,
+            payload,
+        }), "utf8");
+        return {
+            outputDir,
+            entryHtmlPath,
+            snapshotPath,
+        };
+    }
+    finally {
+        try {
+            await dryRuntime.dispose();
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+}
+//# sourceMappingURL=exportDocs.js.map

package/dist/exportDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exportDocs.js","sourceRoot":"","sources":["../src/exportDocs.ts"],"names":[],"mappings":"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"}