@apimatic/cli 1.5.0 → 2.0.0-beta.1

package/lib/types/portal/generation-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-status.js","sourceRoot":"","sources":["../../../src/types/portal/generation-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAN,IAAY,+BASX;AATD,WAAY,+BAA+B;IACzC,oDAAiB,CAAA;IACjB,wEAAqC,CAAA;IACrC,8EAA2C,CAAA;IAC3C,0DAAuB,CAAA;IACvB,oDAAiB,CAAA;IACjB,sEAAmC,CAAA;IACnC,0EAAuC,CAAA;IACvC,sDAAmB,CAAA;AACrB,CAAC,EATW,+BAA+B,KAA/B,+BAA+B,QAS1C"}

package/lib/types/portal/openapi-document.d.ts

@@ -0,0 +1,48 @@
+import { DirectoryPath } from '../file/directoryPath.js';
+import { FileName } from '../file/fileName.js';
+import { FilePath } from '../file/filePath.js';
+import { SuggestedSite } from './config/site-config.js';
+import { Endpoint } from './endpoint.js';
+/**
+ * Whether a parsed document is one a portal can be built from. `format` names what it is
+ * instead when that can be told from the document, and is null when nothing identifies it --
+ * a Postman collection, or any other JSON that carries no version key at all.
+ */
+export type SpecFormat = {
+    supported: true;
+} | {
+    supported: false;
+    format: string | null;
+};
+/** A path item kept in another file, where `pointer` locates it; empty for the whole file. */
+export interface PathItemReference {
+    path: string;
+    file: FilePath;
+    pointer: string;
+}
+/** A specification as written to disk, read the one way the wizard and the build agree on. */
+export declare class OpenApiDocument {
+    private readonly document;
+    private constructor();
+    /**
+     * Undefined when neither parser accepts the text. A document that parses to something other
+     * than an object is kept, and reports itself as no specification at all.
+     */
+    static parse(fileName: FileName, contents: string): OpenApiDocument | undefined;
+    /** Every operation declared inline or behind a `$ref` into this document; see `pathItemReferences` for the rest. */
+    endpoints(): Endpoint[];
+    /** The path items kept in other local files, resolved against the `directory` this document sits in. */
+    pathItemReferences(directory: DirectoryPath): PathItemReference[];
+    /** The operations of the path item `pointer` locates in this document, as they are mounted at `path`. */
+    endpointsAt(path: string, pointer: string): Endpoint[];
+    format(): SpecFormat;
+    /**
+     * Both fields are written into generated files, so each is collapsed to one line. The
+     * description stops at its first blank line: past it a specification's description is
+     * usually a guide to the API, not a summary of it.
+     */
+    suggestedSite(): SuggestedSite;
+    private paths;
+    private endpointsOf;
+    private followLocal;
+}

package/lib/types/portal/openapi-document.js

@@ -0,0 +1,138 @@
+import { basename, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { FileName } from '../file/fileName.js';
+import { FilePath } from '../file/filePath.js';
+import { isJsonObject } from '../../utils/json-utils.js';
+import { stripByteOrderMark } from '../../utils/string-utils.js';
+import { PLACEHOLDER_SITE } from './config/site-config.js';
+import { Endpoint } from './endpoint.js';
+const DESCRIPTION_LIMIT = 300;
+const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
+// The options @scalar/json-magic bundles with, so a spec reads here as it does in the portal.
+const YAML_OPTIONS = { merge: true, maxAliasCount: 10000 };
+/** A specification as written to disk, read the one way the wizard and the build agree on. */
+export class OpenApiDocument {
+    document;
+    constructor(document) {
+        this.document = document;
+    }
+    /**
+     * Undefined when neither parser accepts the text. A document that parses to something other
+     * than an object is kept, and reports itself as no specification at all.
+     */
+    static parse(fileName, contents) {
+        try {
+            // JSON is valid YAML, but the YAML parser is far slower and specs run to megabytes,
+            // so each extension gets the parser built for it.
+            const text = stripByteOrderMark(contents);
+            const document = fileName.hasExtension('.json') ? JSON.parse(text) : parseYaml(text, YAML_OPTIONS);
+            return new OpenApiDocument(isJsonObject(document) ? document : {});
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Every operation declared inline or behind a `$ref` into this document; see `pathItemReferences` for the rest. */
+    endpoints() {
+        return Object.entries(this.paths()).flatMap(([path, pathItem]) => this.endpointsOf(path, pathItem));
+    }
+    /** The path items kept in other local files, resolved against the `directory` this document sits in. */
+    pathItemReferences(directory) {
+        return Object.entries(this.paths()).flatMap(([path, pathItem]) => {
+            const reference = isJsonObject(pathItem) && typeof pathItem.$ref === 'string' ? pathItem.$ref : '';
+            const [file, pointer = ''] = reference.split('#');
+            if (file === '' || URL_SCHEME.test(file)) {
+                return [];
+            }
+            return [{ path, file: new FilePath(directory.resolve(dirname(file)), new FileName(basename(file))), pointer }];
+        });
+    }
+    /** The operations of the path item `pointer` locates in this document, as they are mounted at `path`. */
+    endpointsAt(path, pointer) {
+        return this.endpointsOf(path, valueAt(this.document, pointer));
+    }
+    format() {
+        const openapi = this.document.openapi;
+        if (typeof openapi === 'string') {
+            return openapi.startsWith('3.') ? { supported: true } : { supported: false, format: `OpenAPI ${openapi}` };
+        }
+        if (this.document.swagger !== undefined) {
+            return { supported: false, format: `Swagger ${versionLabel(this.document.swagger)}` };
+        }
+        if (this.document.asyncapi !== undefined) {
+            return { supported: false, format: `AsyncAPI ${versionLabel(this.document.asyncapi)}` };
+        }
+        return { supported: false, format: null };
+    }
+    /**
+     * Both fields are written into generated files, so each is collapsed to one line. The
+     * description stops at its first blank line: past it a specification's description is
+     * usually a guide to the API, not a summary of it.
+     */
+    suggestedSite() {
+        const info = this.document.info;
+        const fields = isJsonObject(info) ? info : {};
+        const name = oneLine(fields.title) ?? PLACEHOLDER_SITE.name;
+        const description = oneLine(firstParagraph(fields.description));
+        return { name, description: description === null ? null : cap(description, DESCRIPTION_LIMIT) };
+    }
+    paths() {
+        return isJsonObject(this.document.paths) ? this.document.paths : {};
+    }
+    endpointsOf(path, pathItem) {
+        return Object.entries(this.followLocal(pathItem, new Set()))
+            .filter(([key, value]) => HTTP_METHODS.has(key.toLowerCase()) && isJsonObject(value))
+            .map(([method]) => new Endpoint(method, path));
+    }
+    // Siblings of a `$ref` override what it points to, as the portal bundles a path item.
+    followLocal(pathItem, seen) {
+        if (!isJsonObject(pathItem)) {
+            return {};
+        }
+        const { $ref, ...siblings } = pathItem;
+        if (typeof $ref !== 'string' || !$ref.startsWith('#') || seen.has($ref)) {
+            return siblings;
+        }
+        seen.add($ref);
+        return { ...this.followLocal(valueAt(this.document, $ref.slice(1)), seen), ...siblings };
+    }
+}
+function valueAt(document, pointer) {
+    try {
+        const segments = pointer
+            .split('/')
+            .slice(1)
+            .map((segment) => decodeURIComponent(segment));
+        return segments.reduce((node, segment) => (isJsonObject(node) ? node[segment.replace(/~1/g, '/').replace(/~0/g, '~')] : undefined), document);
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstParagraph(value) {
+    return typeof value === 'string' ? value.trim().split(/\n\s*\n/)[0] : value;
+}
+// Version keys are strings in well-formed documents; anything else is named rather than
+// stringified into `[object Object]`.
+function versionLabel(version) {
+    return typeof version === 'string' || typeof version === 'number' ? `${version}` : '(unknown version)';
+}
+function oneLine(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length > 0 ? collapsed : null;
+}
+// Cuts on a word boundary when one is near enough the limit, so the site description does
+// not end mid-word.
+function cap(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    const cut = value.slice(0, limit);
+    const lastSpace = cut.lastIndexOf(' ');
+    return (lastSpace > limit - 40 ? cut.slice(0, lastSpace) : cut).trimEnd();
+}
+//# sourceMappingURL=openapi-document.js.map

package/lib/types/portal/openapi-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-document.js","sourceRoot":"","sources":["../../../src/types/portal/openapi-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAc,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAiB,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAgBzC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAEpG,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEzC,8FAA8F;AAC9F,MAAM,YAAY,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAE3D,8FAA8F;AAC9F,MAAM,OAAO,eAAe;IACW,QAAQ;IAA7C,YAAqC,QAAoB;wBAApB,QAAQ;IAAe,CAAC;IAE7D;;;OAGG;IACI,MAAM,CAAC,KAAK,CAAC,QAAkB,EAAE,QAAgB;QACtD,IAAI,CAAC;YACH,oFAAoF;YACpF,kDAAkD;YAClD,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC1C,MAAM,QAAQ,GAAY,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;YAC5G,OAAO,IAAI,eAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,oHAAoH;IAC7G,SAAS;QACd,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACtG,CAAC;IAED,wGAAwG;IACjG,kBAAkB,CAAC,SAAwB;QAChD,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE;YAC/D,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACnG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAClD,IAAI,IAAI,KAAK,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACjH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yGAAyG;IAClG,WAAW,CAAC,IAAY,EAAE,OAAe;QAC9C,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,CAAC;IAEM,MAAM;QACX,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,OAAO,EAAE,EAAE,CAAC;QAC7G,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QACxF,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QAC1F,CAAC;QACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACI,aAAa;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAChC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;QAChE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,CAAC;IAClG,CAAC;IAEO,KAAK;QACX,OAAO,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,CAAC;IAEO,WAAW,CAAC,IAAY,EAAE,QAAiB;QACjD,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;aACzD,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;aACpF,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,sFAAsF;IAC9E,WAAW,CAAC,QAAiB,EAAE,IAAiB;QACtD,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC;QACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,OAAO,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC3F,CAAC;CACF;AAED,SAAS,OAAO,CAAC,QAAoB,EAAE,OAAe;IACpD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,OAAO;aACrB,KAAK,CAAC,GAAG,CAAC;aACV,KAAK,CAAC,CAAC,CAAC;aACR,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;QACjD,OAAO,QAAQ,CAAC,MAAM,CACpB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAC3G,QAAQ,CACT,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9E,CAAC;AAED,wFAAwF;AACxF,sCAAsC;AACtC,SAAS,YAAY,CAAC,OAAgB;IACpC,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;AACzG,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,0FAA0F;AAC1F,oBAAoB;AACpB,SAAS,GAAG,CAAC,KAAa,EAAE,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,SAAS,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;AAC5E,CAAC"}

package/lib/types/portal/page-fragments.d.ts

@@ -0,0 +1,13 @@
+import { FileName } from '../file/fileName.js';
+export declare const GENERATED_INCLUDES_DIRECTORY_NAME = "generated-includes";
+export declare const SDK_DOCS_FOLDER = "sdk-docs";
+/** One Markdown file a generated page includes, with the folder it goes in. */
+export interface PageFragment {
+    folder: string;
+    fileName: FileName;
+    contents: string;
+}
+/** Where a language's SDK docs are written, from the root of the portal project. */
+export declare function sdkDocsPath(language: string): string;
+/** Included rather than held, so MDX compiles them as Markdown, where a `{` or `<` is only text. */
+export declare function pageFragments(sdkDocs: ReadonlyMap<string, string>): PageFragment[];

package/lib/types/portal/page-fragments.js

@@ -0,0 +1,24 @@
+import { FileName } from '../file/fileName.js';
+// Beside the generated directory, not in it: there the collection and the prerender would take each for a page.
+export const GENERATED_INCLUDES_DIRECTORY_NAME = 'generated-includes';
+export const SDK_DOCS_FOLDER = 'sdk-docs';
+/** Where a language's SDK docs are written, from the root of the portal project. */
+export function sdkDocsPath(language) {
+    return [GENERATED_INCLUDES_DIRECTORY_NAME, SDK_DOCS_FOLDER, `${sdkDocsFileName(language)}`].join('/');
+}
+/** Included rather than held, so MDX compiles them as Markdown, where a `{` or `<` is only text. */
+export function pageFragments(sdkDocs) {
+    return [...sdkDocs].map(([language, markdown]) => ({
+        folder: SDK_DOCS_FOLDER,
+        fileName: sdkDocsFileName(language),
+        contents: markdownFile(markdown)
+    }));
+}
+function sdkDocsFileName(language) {
+    return new FileName(`${language}.md`);
+}
+function markdownFile(text) {
+    const trimmed = text.trimEnd();
+    return trimmed.length === 0 ? '' : `${trimmed}\n`;
+}
+//# sourceMappingURL=page-fragments.js.map

package/lib/types/portal/page-fragments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-fragments.js","sourceRoot":"","sources":["../../../src/types/portal/page-fragments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,gHAAgH;AAChH,MAAM,CAAC,MAAM,iCAAiC,GAAG,oBAAoB,CAAC;AAEtE,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;AAS1C,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,CAAC,iCAAiC,EAAE,eAAe,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxG,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAAC,OAAoC;IAChE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,MAAM,EAAE,eAAe;QACvB,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;QACnC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC;KACjC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB;IACvC,OAAO,IAAI,QAAQ,CAAC,GAAG,QAAQ,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC;AACpD,CAAC"}

package/lib/types/portal/page-template.d.ts

@@ -0,0 +1,15 @@
+import { Result } from 'neverthrow';
+import { FileName } from '../file/fileName.js';
+export type PageRecord = Readonly<Record<string, string>>;
+/** A page's values: strings for its placeholders, and lists of records for its sections. */
+export type PageValues = Readonly<Record<string, string | readonly PageRecord[]>>;
+/** Refuses a tag MDX would misread; inside a section, tags are checked per item, so an empty list checks none. */
+export declare class PageTemplate {
+    private readonly fileName;
+    private readonly text;
+    constructor(fileName: FileName, text: string);
+    render(values: PageValues): Result<string, string>;
+    /** `scopes` runs from the page's own values to the innermost section's item, as mustache looks names up. */
+    private problemIn;
+    private problemWith;
+}

package/lib/types/portal/page-template.js

@@ -0,0 +1,64 @@
+import Mustache from 'mustache';
+import { err, ok } from 'neverthrow';
+import { errorMessage } from '../../utils/error-utils.js';
+const KEY = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** The tags a page may use besides comments: placeholders, sections and inverted sections. */
+const TAG_TYPES = ['name', '#', '^'];
+// The values are MDX source, which reads its own braces and tags, so nothing is escaped.
+const RENDER_OPTIONS = { escape: (value) => String(value) };
+/** Refuses a tag MDX would misread; inside a section, tags are checked per item, so an empty list checks none. */
+export class PageTemplate {
+    fileName;
+    text;
+    constructor(fileName, text) {
+        this.fileName = fileName;
+        this.text = text;
+    }
+    render(values) {
+        let tokens;
+        try {
+            tokens = Mustache.parse(this.text);
+        }
+        catch (error) {
+            return err(`${this.fileName}: ${errorMessage(error)}`);
+        }
+        const problem = this.problemIn(tokens, [values]);
+        return problem === undefined ? ok(Mustache.render(this.text, values, {}, RENDER_OPTIONS)) : err(problem);
+    }
+    /** `scopes` runs from the page's own values to the innermost section's item, as mustache looks names up. */
+    problemIn(tokens, scopes) {
+        for (const token of tokens) {
+            const problem = this.problemWith(token, scopes);
+            if (problem !== undefined) {
+                return problem;
+            }
+        }
+        return undefined;
+    }
+    problemWith(token, scopes) {
+        const [type, key, start, end] = token;
+        if (type === 'text' || type === '!') {
+            return undefined;
+        }
+        const tag = this.text.slice(start, end);
+        if (!TAG_TYPES.includes(type) || !KEY.test(key)) {
+            // Most likely a JSX object, `{{ ... }}`, which a space between the braces keeps out of the tags.
+            return (`${this.fileName}: '${tag}' is not a placeholder. A placeholder is {{key}} and a section ` +
+                `{{#key}}...{{/key}}; write a JSX object as '{ { ... } }'.`);
+        }
+        const value = [...scopes].reverse().find((scope) => Object.hasOwn(scope, key))?.[key];
+        if (value === undefined) {
+            return `${this.fileName}: '${tag}' names a value the page is not given.`;
+        }
+        if (type === 'name') {
+            return typeof value === 'string'
+                ? undefined
+                : `${this.fileName}: '${tag}' names a list, which is written as a section, {{#${key}}}...{{/${key}}}.`;
+        }
+        // A section over a list is read once per item; any other section in the scopes it stands in.
+        const inner = token[4];
+        const itemScopes = type === '#' && typeof value !== 'string' ? value.map((item) => [...scopes, item]) : [scopes];
+        return itemScopes.map((itemScope) => this.problemIn(inner, itemScope)).find((problem) => problem !== undefined);
+    }
+}
+//# sourceMappingURL=page-template.js.map

package/lib/types/portal/page-template.js.map

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

package/lib/types/portal/page.d.ts

@@ -0,0 +1,24 @@
+import { Result } from 'neverthrow';
+import { FileName } from '../file/fileName.js';
+/** What the build reads from a page's front matter that the CLI needs. */
+export interface PageFrontMatter {
+    /** What the sidebar and a tab name the page by. */
+    title: string;
+}
+/** A Markdown image the build imports, where it looks for the file, and the path it looks up there. */
+export interface PageImage {
+    /** As the page writes it. */
+    url: string;
+    line: number;
+    /** An image written as `/…` is read from the static directory, any other from beside its page. */
+    from: 'static' | 'page';
+    /** Decoded, without its query or fragment, with `/` between segments. */
+    path: string;
+}
+/** A page as the build parses it: its front matter held to the build's schema, and the images the build imports. */
+export interface ParsedPage {
+    frontMatter: Result<PageFrontMatter, string[]>;
+    images: PageImage[];
+}
+/** Parsed once, as the build parses it, `.mdx` as MDX; a body that does not parse is the build's to report. */
+export declare function parsePage(contents: string, fileName: FileName, label: string): Promise<ParsedPage>;

package/lib/types/portal/page.js

@@ -0,0 +1,100 @@
+import { frontmatter } from 'fumadocs-core/content/md/frontmatter';
+import { err, ok } from 'neverthrow';
+import { errorMessage } from '../../utils/error-utils.js';
+import { isJsonObject } from '../../utils/json-utils.js';
+const EXPECTED = { string: 'text', boolean: 'true or false' };
+// A scheme, a drive letter or a network path: none of them names a file the build imports.
+const NOT_A_FILE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+/** Parsed once, as the build parses it, `.mdx` as MDX; a body that does not parse is the build's to report. */
+export async function parsePage(contents, fileName, label) {
+    let parsed;
+    try {
+        parsed = frontmatter(contents);
+    }
+    catch (error) {
+        const reason = errorMessage(error).split('\n')[0];
+        return { frontMatter: err([`${label}: its front matter is not valid YAML. ${reason}`]), images: [] };
+    }
+    // Blanked rather than cut, so every line keeps its number.
+    const body = '\n'.repeat(parsed.matter.split('\n').length - 1) + contents.slice(parsed.matter.length);
+    return {
+        frontMatter: await checkedFrontMatter(parsed, label),
+        images: await imagesIn(body, fileName.hasExactExtension('.mdx'))
+    };
+}
+/** Held to the build's own schema, which fails the whole build over one page. */
+async function checkedFrontMatter({ matter, data }, label) {
+    if (matter.length === 0) {
+        return err([`${label} has no front matter, which is where its title goes.`]);
+    }
+    // On first use: zod, which the schema is written in, adds a tenth of a second to every command's start.
+    const { pageSchema: schema } = await import('fumadocs-core/source/schema');
+    const fields = isJsonObject(data) ? data : {};
+    const checked = schema.safeParse(fields);
+    if (!checked.success) {
+        return err(checked.error.issues.map((issue) => describeIssue(issue, fields, label)));
+    }
+    // The schema takes an empty title, and the page is then a blank entry in the sidebar.
+    if (checked.data.title.trim().length === 0) {
+        return err([`${label}: 'title' must not be empty.`]);
+    }
+    return ok({ title: checked.data.title });
+}
+function describeIssue(issue, fields, label) {
+    const field = issue.path.join('.');
+    if (field === 'title') {
+        return titleError(fields.title, label);
+    }
+    const expected = issue.code === 'invalid_type' ? EXPECTED[issue.expected] : undefined;
+    return expected === undefined
+        ? `${label}: '${field}': ${issue.message}.`
+        : `${label}: '${field}' must be ${expected}.`;
+}
+function titleError(title, label) {
+    if (title === undefined) {
+        return `${label} has no 'title' in its front matter.`;
+    }
+    if (title === null) {
+        return `${label}: 'title' must not be empty.`;
+    }
+    return `${label}: 'title' must be text. Put it in quotes if it looks like a number or true or false.`;
+}
+async function imagesIn(body, isMdx) {
+    // On first use, as the schema is: most commands never read a page.
+    const { remark } = await import('remark');
+    const processor = isMdx ? remark().use((await import('remark-mdx')).default) : remark();
+    let tree;
+    try {
+        tree = processor.parse(body);
+    }
+    catch {
+        return [];
+    }
+    const images = [];
+    const visit = (node) => {
+        const image = node.type === 'image' && node.url !== undefined ? located(node.url) : null;
+        if (image !== null) {
+            images.push({ ...image, line: node.position?.start.line ?? 0 });
+        }
+        node.children?.forEach(visit);
+    };
+    visit(tree);
+    return images;
+}
+function located(url) {
+    const address = url.split(/[?#]/, 1)[0];
+    if (address.length === 0 || address.endsWith('/') || NOT_A_FILE.test(address)) {
+        return null;
+    }
+    const path = decodedAddress(address);
+    return path.startsWith('/') ? { url, from: 'static', path: path.replace(/^\/+/, '') } : { url, from: 'page', path };
+}
+function decodedAddress(address) {
+    try {
+        return decodeURI(address);
+    }
+    catch {
+        return address;
+    }
+}
+//# sourceMappingURL=page.js.map

package/lib/types/portal/page.js.map

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

package/lib/types/portal/portal-artifacts.d.ts

@@ -0,0 +1,25 @@
+import { FilePath } from '../file/filePath.js';
+import { CodeSampleCatalogs } from './code-samples.js';
+/**
+ * What one `/portal-artifacts` run delivered, unpacked and read but not yet placed. The samples
+ * and the SDK docs are in memory because the build merges or includes them; the SDKs and the
+ * plugin are still files, because placing them is copying them.
+ *
+ * The paths point inside the directory the caller handed to `generate`, so they live exactly as
+ * long as that directory does.
+ */
+export declare class PortalArtifacts {
+    readonly codeSampleCatalogs: CodeSampleCatalogs;
+    /** Keyed by the language name the server delivered, which is what it is placed under. */
+    readonly sdks: ReadonlyMap<string, FilePath>;
+    /** Each language's getting-started Markdown, keyed as `sdks` is. */
+    readonly sdkDocs: ReadonlyMap<string, string>;
+    readonly plugin: FilePath | undefined;
+    constructor(codeSampleCatalogs: CodeSampleCatalogs, 
+    /** Keyed by the language name the server delivered, which is what it is placed under. */
+    sdks: ReadonlyMap<string, FilePath>, 
+    /** Each language's getting-started Markdown, keyed as `sdks` is. */
+    sdkDocs: ReadonlyMap<string, string>, plugin: FilePath | undefined);
+    /** A run that was never made: a portal declaring no languages and no plugin has nothing to ask for. */
+    static none(): PortalArtifacts;
+}

package/lib/types/portal/portal-artifacts.js

@@ -0,0 +1,30 @@
+import { CodeSampleCatalogs } from './code-samples.js';
+/**
+ * What one `/portal-artifacts` run delivered, unpacked and read but not yet placed. The samples
+ * and the SDK docs are in memory because the build merges or includes them; the SDKs and the
+ * plugin are still files, because placing them is copying them.
+ *
+ * The paths point inside the directory the caller handed to `generate`, so they live exactly as
+ * long as that directory does.
+ */
+export class PortalArtifacts {
+    codeSampleCatalogs;
+    sdks;
+    sdkDocs;
+    plugin;
+    constructor(codeSampleCatalogs, 
+    /** Keyed by the language name the server delivered, which is what it is placed under. */
+    sdks, 
+    /** Each language's getting-started Markdown, keyed as `sdks` is. */
+    sdkDocs, plugin) {
+        this.codeSampleCatalogs = codeSampleCatalogs;
+        this.sdks = sdks;
+        this.sdkDocs = sdkDocs;
+        this.plugin = plugin;
+    }
+    /** A run that was never made: a portal declaring no languages and no plugin has nothing to ask for. */
+    static none() {
+        return new PortalArtifacts(new CodeSampleCatalogs([]), new Map(), new Map(), undefined);
+    }
+}
+//# sourceMappingURL=portal-artifacts.js.map

package/lib/types/portal/portal-artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal-artifacts.js","sourceRoot":"","sources":["../../../src/types/portal/portal-artifacts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IAER,kBAAkB;IAElB,IAAI;IAEJ,OAAO;IACP,MAAM;IANxB,YACkB,kBAAsC;IACtD,yFAAyF;IACzE,IAAmC;IACnD,oEAAoE;IACpD,OAAoC,EACpC,MAA4B;kCAL5B,kBAAkB;oBAElB,IAAI;uBAEJ,OAAO;sBACP,MAAM;IACrB,CAAC;IAEJ,uGAAuG;IAChG,MAAM,CAAC,IAAI;QAChB,OAAO,IAAI,eAAe,CAAC,IAAI,kBAAkB,CAAC,EAAE,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;IAC1F,CAAC;CACF"}

package/lib/types/portal/portal-config.d.ts

@@ -0,0 +1,69 @@
+import { Result } from 'neverthrow';
+import { UrlPath } from '../file/urlPath.js';
+import { AiConfig } from './config/ai-config.js';
+import { BrandConfig, ColorMode } from './config/brand-config.js';
+import { NavigationConfig } from './config/navigation-config.js';
+import { SiteConfig, SuggestedSite } from './config/site-config.js';
+import { StaticAsset } from './config/static-asset.js';
+export interface PortalLink {
+    label: string;
+    url: string;
+    /** Whether it leaves the portal, which opens it in a new tab. */
+    external: boolean;
+}
+/**
+ * What the browser bundle is told about the portal, written to `portal.identity.json`. Nothing
+ * here may address the machine the portal was built on. `portal-template/src/lib/portal-types.ts`
+ * declares the same type, and test/portal-template.test.ts holds the two equal.
+ */
+export interface PortalIdentity {
+    name: string;
+    description: string | null;
+    /** Origin only, with no trailing slash. */
+    siteUrl: string | null;
+    /** Site-relative, one per colour mode; the same URL twice when one image serves both. */
+    logo: {
+        light: string;
+        dark: string;
+    } | null;
+    /** Site-relative, with the image type its extension names, when it names one. */
+    favicon: {
+        url: string;
+        type: string | null;
+    } | null;
+    colorMode: ColorMode;
+    links: PortalLink[];
+    /** Whether each page offers to open itself in an external AI assistant. */
+    pageActions: boolean;
+}
+export declare class PortalConfig {
+    private readonly site;
+    private readonly brand;
+    private readonly navigation;
+    private readonly ai;
+    private readonly pluginAddress;
+    private constructor();
+    /** The block quickstart writes: the specification's own name and description, and every default spelled out. */
+    static scaffolded(site: SuggestedSite): PortalConfig;
+    /**
+     * `block` is whatever the file holds under `portal`. `suggested` is what the only specification
+     * says about itself, or null when there are several; it fills the site's name and description
+     * when the block leaves them out.
+     */
+    static fromBlock(block: unknown, suggested: SuggestedSite | null): Result<PortalConfig, string[]>;
+    siteTitle(): string;
+    /** Where the context plugin is hosted when it is not bundled into the portal, or null when it is. */
+    pluginUrl(): UrlPath | null;
+    brandSettings(): BrandConfig;
+    staticFiles(): StaticAsset[];
+    identity(): PortalIdentity;
+    /** Every namespace included, defaults and all, which is what quickstart writes. */
+    toJSON(): PortalBlock;
+}
+export interface PortalBlock {
+    site: ReturnType<SiteConfig['toJSON']>;
+    brand: ReturnType<BrandConfig['toJSON']>;
+    navigation: ReturnType<NavigationConfig['toJSON']>;
+    ai: ReturnType<AiConfig['toJSON']>;
+    pluginUrl?: string;
+}