@apimatic/cli 1.5.0 → 2.0.0-beta.1

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

@@ -0,0 +1,129 @@
+import { DirectoryPath } from '../file/directoryPath.js';
+import { FileName } from '../file/fileName.js';
+import { FilePath } from '../file/filePath.js';
+import { Endpoint } from './endpoint.js';
+import { SuggestedSite } from './config/site-config.js';
+import { ContentNotices } from './content-notices.js';
+import { GeneratedPages, GeneratedSection } from './generated-pages.js';
+import { PortalConfig } from './portal-config.js';
+/** An OpenAPI document found in `src/spec/`, with the slug its section is mounted at. */
+export interface PortalSpec {
+    slug: string;
+    file: FilePath;
+    /** Its operations, including those behind a `$ref` path item. */
+    endpoints: Endpoint[];
+}
+/** What `apimatic.json` decides about a portal, which `portal serve` reads again on every edit. */
+export interface PortalSettings {
+    config: PortalConfig;
+    generatedPages: GeneratedPages;
+}
+/** A validated portal source directory, ready to be built. */
+export interface PortalSource extends PortalSettings {
+    /**
+     * What the only specification says about itself, or null with several. Kept so `portal serve`
+     * can judge an edited config without reading the specifications again.
+     */
+    suggestedSite: SuggestedSite | null;
+    specs: PortalSpec[];
+    contentDirectory: DirectoryPath | null;
+    staticDirectory: DirectoryPath | null;
+    shadowedFiles: FileName[];
+    contentNotices: ContentNotices;
+}
+/** Why a source directory could not be written; each variant maps to its own message. */
+export type PortalScaffoldProblem = {
+    kind: 'configUnreadable';
+} | {
+    kind: 'configUnwritable';
+} | {
+    kind: 'sourceUnwritable';
+    reason: string;
+};
+/** A file the build reads and cannot find. */
+export interface MissingFile {
+    file: FilePath;
+    /**
+     * The same file in another case, when there is one. Found here because Windows and macOS
+     * ignore case, but a link in it 404s on the hosts portals are published to, which do not.
+     */
+    foundAs: FilePath | null;
+}
+/** A file `apimatic.json` names, by the setting that names it. */
+export interface MissingStaticFile extends MissingFile {
+    setting: string;
+}
+/** A page of the user's served at an address the CLI keeps for the pages it generates. */
+export interface ReservedAddressPage {
+    file: FilePath;
+    /** Where the page would be served, which a `(group)` folder makes differ from its path. */
+    address: string;
+    section: GeneratedSection;
+}
+/** Pages of the user's that would be served at one address, which only one of them can have. */
+export interface SharedAddress {
+    address: string;
+    pages: FilePath[];
+}
+/** A page's Markdown image that the build would import and not find, which fails the whole build. */
+export interface MissingImage {
+    page: FilePath;
+    line: number;
+    url: string;
+    /** Null for an image beside its page that points out of `content/`'s copy, which the build never looks for. */
+    missing: MissingFile | null;
+}
+/** Why `content/` cannot be built; each variant maps to its own message. */
+export type ContentProblem = {
+    kind: 'unreadableContent';
+} | {
+    kind: 'groupNamedPages';
+    pages: FilePath[];
+} | {
+    kind: 'reservedAddresses';
+    pages: ReservedAddressPage[];
+} | {
+    kind: 'sharedAddresses';
+    addresses: SharedAddress[];
+} | {
+    kind: 'invalidFrontMatter';
+    errors: string[];
+} | {
+    kind: 'invalidNavigation';
+    errors: string[];
+} | {
+    kind: 'missingImages';
+    images: MissingImage[];
+};
+/** How `api transform` would turn the first document in `spec/` into one the portal reads. */
+export interface SpecConversion {
+    file: FilePath;
+    /** What the document is instead, when it says; null for one that names no format. */
+    format: string | null;
+    /** Where `api transform --destination` of `spec/` writes it, which is one folder too deep. */
+    converted: FilePath;
+    others: number;
+}
+/** Why a source directory cannot be built; each variant maps to its own message. */
+export type PortalSourceProblem = {
+    kind: 'missingConfig';
+} | {
+    kind: 'invalidConfig';
+    errors: string[];
+    missingPortal: boolean;
+} | {
+    kind: 'invalidContent';
+    problems: ContentProblem[];
+} | {
+    kind: 'unreadableSpec';
+    fileName: FileName;
+} | {
+    kind: 'emptySpecDirectory';
+    folders: DirectoryPath[];
+} | {
+    kind: 'noOpenApiSpec';
+    conversion: SpecConversion;
+} | {
+    kind: 'missingStaticFiles';
+    files: MissingStaticFile[];
+};

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=portal-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portal-source.js","sourceRoot":"","sources":["../../../src/types/portal/portal-source.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,19 @@
+import { PortalConfig } from './portal-config.js';
+/**
+ * Scoped with `:not(.dark)`: a bare `:root` has the specificity of the theme's `.dark` block and
+ * comes after it, so a colour meant for light mode would win in dark mode too.
+ */
+export declare const LIGHT_SELECTOR = ":root:not(.dark)";
+export declare const DARK_SELECTOR = ".dark";
+/**
+ * The build project's `src/styles/theme.css`. `app.css` imports it after the Fumadocs theme,
+ * so what it sets comes last. A file of its own rather than a substitution, so `portal serve`
+ * can rewrite it whole when the block changes; rendered here so the CSS is tested without a build.
+ */
+export declare class PortalStylesheet {
+    private readonly primary;
+    private constructor();
+    static of(config: PortalConfig): PortalStylesheet;
+    toString(): string;
+    private static rule;
+}

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

@@ -0,0 +1,40 @@
+const HEADER = "/* Written by the APIMatic CLI from the 'portal' block of src/apimatic.json. Edit that instead. */";
+/**
+ * Scoped with `:not(.dark)`: a bare `:root` has the specificity of the theme's `.dark` block and
+ * comes after it, so a colour meant for light mode would win in dark mode too.
+ */
+export const LIGHT_SELECTOR = ':root:not(.dark)';
+export const DARK_SELECTOR = '.dark';
+/**
+ * The build project's `src/styles/theme.css`. `app.css` imports it after the Fumadocs theme,
+ * so what it sets comes last. A file of its own rather than a substitution, so `portal serve`
+ * can rewrite it whole when the block changes; rendered here so the CSS is tested without a build.
+ */
+export class PortalStylesheet {
+    primary;
+    constructor(primary) {
+        this.primary = primary;
+    }
+    static of(config) {
+        return new PortalStylesheet(config.brandSettings().brandColors().primaryColors());
+    }
+    toString() {
+        const rules = this.primary === null
+            ? []
+            : [
+                PortalStylesheet.rule(LIGHT_SELECTOR, this.primary.light),
+                PortalStylesheet.rule(DARK_SELECTOR, this.primary.dark)
+            ];
+        return [HEADER, ...rules].join('\n\n').concat('\n');
+    }
+    static rule(selector, primary) {
+        const declarations = [
+            ['--color-fd-primary', primary.toString()],
+            ['--color-fd-primary-foreground', primary.foreground().toString()],
+            ['--color-fd-ring', primary.toString()]
+        ];
+        const body = declarations.map(([name, value]) => `  ${name}: ${value};`).join('\n');
+        return `${selector} {\n${body}\n}`;
+    }
+}
+//# sourceMappingURL=portal-stylesheet.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portal-stylesheet.js","sourceRoot":"","sources":["../../../src/types/portal/portal-stylesheet.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,GAAG,oGAAoG,CAAC;AAEpH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AAErC;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IACU,OAAO;IAA5C,YAAqC,OAA6C;uBAA7C,OAAO;IAAyC,CAAC;IAE/E,MAAM,CAAC,EAAE,CAAC,MAAoB;QACnC,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,CAAC,aAAa,EAAE,CAAC,CAAC;IACpF,CAAC;IAEM,QAAQ;QACb,MAAM,KAAK,GACT,IAAI,CAAC,OAAO,KAAK,IAAI;YACnB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,gBAAgB,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;gBACzD,gBAAgB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;aACxD,CAAC;QACR,OAAO,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAEO,MAAM,CAAC,IAAI,CAAC,QAAgB,EAAE,OAAc;QAClD,MAAM,YAAY,GAAG;YACnB,CAAC,oBAAoB,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC1C,CAAC,+BAA+B,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;YAClE,CAAC,iBAAiB,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;SACxC,CAAC;QACF,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpF,OAAO,GAAG,QAAQ,OAAO,IAAI,KAAK,CAAC;IACrC,CAAC;CACF"}

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

@@ -0,0 +1,33 @@
+import { DirectoryPath } from '../file/directoryPath.js';
+import { FilePath } from '../file/filePath.js';
+import { GeneratedSection } from './generated-pages.js';
+/** What a tab is made of. */
+export type TabOwner = {
+    kind: 'home';
+} | {
+    kind: 'folder';
+    directory: DirectoryPath;
+} | {
+    kind: 'apiReference';
+} | {
+    kind: 'generated';
+    section: GeneratedSection;
+};
+/** A tab by the name the tab bar shows for it. */
+export interface PortalTab {
+    owner: TabOwner;
+    name: string;
+    /** The `nav.json` or index page whose title gives the name, or null when the portal gives it. */
+    namedBy: FilePath | null;
+}
+/** A name the tab bar would show for more than one tab, which leaves them indistinguishable. */
+export interface SharedTabName {
+    /** As the first of the tabs spells it; the others may differ from it in case. */
+    name: string;
+    tabs: PortalTab[];
+}
+export declare function sharedTabNames(tabs: PortalTab[]): SharedTabName[];
+/** The name the template gives a tab that no title names. */
+export declare function untitledTabName(owner: TabOwner): string;
+/** Fumadocs' name for a folder that nothing names: its directory's, as `pathToName` spells it. */
+export declare function directoryTabName(directoryName: string): string;

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

@@ -0,0 +1,38 @@
+import { GROUP_FOLDER } from './portal-navigation.js';
+// A reader cannot tell Guides from guides in a tab bar any more than Guides from Guides.
+export function sharedTabNames(tabs) {
+    const byName = new Map();
+    for (const tab of tabs) {
+        const key = tab.name.toLowerCase();
+        byName.set(key, [...(byName.get(key) ?? []), tab]);
+    }
+    return [...byName.values()]
+        .filter((named) => named.length > 1)
+        .map((named) => ({ name: named[0].name, tabs: named }));
+}
+/** The name the template gives a tab that no title names. */
+export function untitledTabName(owner) {
+    switch (owner.kind) {
+        case 'home':
+            return 'Home';
+        case 'apiReference':
+            return 'API Reference';
+        case 'generated':
+            return owner.section.title;
+        case 'folder':
+            return directoryTabName(owner.directory.leafName());
+    }
+}
+/** Fumadocs' name for a folder that nothing names: its directory's, as `pathToName` spells it. */
+export function directoryTabName(directoryName) {
+    const name = GROUP_FOLDER.exec(directoryName)?.[1] ?? directoryName;
+    return [...name]
+        .map((character, index) => {
+        if (index === 0) {
+            return character.toLocaleUpperCase();
+        }
+        return character === '-' ? ' ' : character;
+    })
+        .join('');
+}
+//# sourceMappingURL=portal-tabs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"portal-tabs.js","sourceRoot":"","sources":["../../../src/types/portal/portal-tabs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAyBtD,yFAAyF;AACzF,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;SACxB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;SACnC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAC,KAAe;IAC7C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,cAAc;YACjB,OAAO,eAAe,CAAC;QACzB,KAAK,WAAW;YACd,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7B,KAAK,QAAQ;YACX,OAAO,gBAAgB,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,gBAAgB,CAAC,aAAqB;IACpD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC;IACpE,OAAO,CAAC,GAAG,IAAI,CAAC;SACb,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE;QACxB,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,SAAS,CAAC,iBAAiB,EAAE,CAAC;QACvC,CAAC;QACD,OAAO,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7C,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,20 @@
+import { PortalConfig } from './portal-config.js';
+/** The notice is given once, on the save that brings it about, rather than on every save after it. */
+export declare class PreviewConfig {
+    private readonly servesStatic;
+    private shown;
+    private refused;
+    /**
+     * `servesStatic`: the dev server serves `static/` only if it was there at startup, and a
+     * block that names a file in it was refused unless it was.
+     */
+    constructor(startup: PortalConfig, servesStatic: boolean);
+    refuse(): void;
+    staticDirectoryNotServed(config: PortalConfig): boolean;
+    /**
+     * Records the edit as shown, and answers whether to say it was applied: a file fixed back to
+     * what the preview shows writes nothing, but the user was told it was refused, so hears that
+     * it is accepted again.
+     */
+    show(config: PortalConfig, written: boolean): boolean;
+}

package/lib/types/portal/preview-config.js

@@ -0,0 +1,32 @@
+/** The notice is given once, on the save that brings it about, rather than on every save after it. */
+export class PreviewConfig {
+    servesStatic;
+    shown;
+    refused = false;
+    /**
+     * `servesStatic`: the dev server serves `static/` only if it was there at startup, and a
+     * block that names a file in it was refused unless it was.
+     */
+    constructor(startup, servesStatic) {
+        this.servesStatic = servesStatic;
+        this.shown = startup;
+    }
+    refuse() {
+        this.refused = true;
+    }
+    staticDirectoryNotServed(config) {
+        return !this.servesStatic && config.staticFiles().length > 0 && this.shown.staticFiles().length === 0;
+    }
+    /**
+     * Records the edit as shown, and answers whether to say it was applied: a file fixed back to
+     * what the preview shows writes nothing, but the user was told it was refused, so hears that
+     * it is accepted again.
+     */
+    show(config, written) {
+        const announce = written || this.refused;
+        this.refused = false;
+        this.shown = config;
+        return announce;
+    }
+}
+//# sourceMappingURL=preview-config.js.map

package/lib/types/portal/preview-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-config.js","sourceRoot":"","sources":["../../../src/types/portal/preview-config.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,MAAM,OAAO,aAAa;IAQ4B,YAAY;IAPxD,KAAK,CAAe;IACpB,OAAO,GAAG,KAAK,CAAC;IAExB;;;OAGG;IACH,YAAY,OAAqB,EAAmB,YAAqB;4BAArB,YAAY;QAC9D,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,CAAC;IAEM,MAAM;QACX,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAEM,wBAAwB,CAAC,MAAoB;QAClD,OAAO,CAAC,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;IACxG,CAAC;IAED;;;;OAIG;IACI,IAAI,CAAC,MAAoB,EAAE,OAAgB;QAChD,MAAM,QAAQ,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACpB,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/lib/types/portal/preview-content.d.ts

@@ -0,0 +1,18 @@
+import { ContentNotices } from './content-notices.js';
+/** A notice is given once, on the save that brings it about, rather than on every save after it. */
+export declare class PreviewContent {
+    private shown;
+    private refused;
+    /** `startup`: what the checks before the preview started reported. */
+    constructor(startup: ContentNotices);
+    refuse(): void;
+    /**
+     * Records the content as shown, and answers whether to say it is fixed, having been refused,
+     * and which notices to give: each kind in full when it holds something new, and none otherwise.
+     */
+    show(notices: ContentNotices): {
+        fixed: boolean;
+        notices: ContentNotices;
+    };
+    private static since;
+}

package/lib/types/portal/preview-content.js

@@ -0,0 +1,50 @@
+/** A notice is given once, on the save that brings it about, rather than on every save after it. */
+export class PreviewContent {
+    shown;
+    refused = false;
+    /** `startup`: what the checks before the preview started reported. */
+    constructor(startup) {
+        this.shown = startup;
+    }
+    refuse() {
+        this.refused = true;
+    }
+    /**
+     * Records the content as shown, and answers whether to say it is fixed, having been refused,
+     * and which notices to give: each kind in full when it holds something new, and none otherwise.
+     */
+    show(notices) {
+        const shown = { fixed: this.refused, notices: PreviewContent.since(notices, this.shown) };
+        this.refused = false;
+        this.shown = notices;
+        return shown;
+    }
+    static since(current, previous) {
+        return {
+            hiddenPages: whenAnyNew(current.hiddenPages, previous.hiddenPages, (left, right) => left.isEqual(right)),
+            ignoredNavigationFiles: whenAnyNew(current.ignoredNavigationFiles, previous.ignoredNavigationFiles, (left, right) => left.isEqual(right)),
+            folderTabs: whenAnyNew(current.folderTabs, previous.folderTabs, (left, right) => left.isEqual(right)),
+            sharedTabNames: whenAnyNew(current.sharedTabNames, previous.sharedTabNames, isSameSharedName)
+        };
+    }
+}
+function whenAnyNew(current, previous, isSame) {
+    return current.some((item) => !previous.some((earlier) => isSame(item, earlier))) ? current : [];
+}
+/** The same name on the same tabs, whichever file gives it to each. */
+function isSameSharedName(left, right) {
+    return (left.name === right.name &&
+        left.tabs.length === right.tabs.length &&
+        left.tabs.every((tab) => right.tabs.some((other) => isSameOwner(tab.owner, other.owner))));
+}
+function isSameOwner(left, right) {
+    switch (left.kind) {
+        case 'folder':
+            return right.kind === 'folder' && left.directory.isEqual(right.directory);
+        case 'generated':
+            return right.kind === 'generated' && left.section === right.section;
+        default:
+            return left.kind === right.kind;
+    }
+}
+//# sourceMappingURL=preview-content.js.map

package/lib/types/portal/preview-content.js.map

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

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

@@ -0,0 +1,12 @@
+import { UrlPath } from '../file/urlPath.js';
+import { Language } from '../sdk/generate.js';
+/** A released SDK package, as its public registry lists it. */
+export interface PublishedPackage {
+    name: string;
+    registry: string;
+    url: UrlPath;
+    /** The shell command that adds the package to a project. */
+    install: string;
+}
+/** Null when the configuration does not name the package, which the backend's validation reports. */
+export declare function publishedPackage(language: Language, configuration: Readonly<Record<string, unknown>>): PublishedPackage | null;

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

@@ -0,0 +1,35 @@
+import { UrlPath } from '../file/urlPath.js';
+import { Language } from '../sdk/generate.js';
+// The public registry of each language the portal supports; a private one is not told apart.
+const REGISTRIES = {
+    [Language.TYPESCRIPT]: {
+        name: 'npm',
+        nameField: 'name',
+        // `encodeURI` keeps a scoped name's `@` and `/`, which npm addresses as they are.
+        address: (packageName) => `https://www.npmjs.com/package/${encodeURI(packageName)}`,
+        install: (packageName) => `npm install ${packageName}`
+    },
+    [Language.PYTHON]: {
+        name: 'PyPI',
+        nameField: 'name',
+        address: (packageName) => `https://pypi.org/project/${encodeURIComponent(packageName)}/`,
+        install: (packageName) => `pip install ${packageName}`
+    },
+    [Language.CSHARP]: {
+        name: 'NuGet',
+        nameField: 'packageId',
+        address: (packageName) => `https://www.nuget.org/packages/${encodeURIComponent(packageName)}`,
+        install: (packageName) => `dotnet add package ${packageName}`
+    }
+};
+/** Null when the configuration does not name the package, which the backend's validation reports. */
+export function publishedPackage(language, configuration) {
+    const registry = REGISTRIES[language];
+    const field = registry === undefined ? undefined : configuration[registry.nameField];
+    const name = typeof field === 'string' ? field.trim() : '';
+    if (registry === undefined || name.length === 0) {
+        return null;
+    }
+    return { name, registry: registry.name, url: new UrlPath(registry.address(name)), install: registry.install(name) };
+}
+//# sourceMappingURL=published-package.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"published-package.js","sourceRoot":"","sources":["../../../src/types/portal/published-package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAkB9C,6FAA6F;AAC7F,MAAM,UAAU,GAA6C;IAC3D,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE;QACrB,IAAI,EAAE,KAAK;QACX,SAAS,EAAE,MAAM;QACjB,kFAAkF;QAClF,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,iCAAiC,SAAS,CAAC,WAAW,CAAC,EAAE;QACnF,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,eAAe,WAAW,EAAE;KACvD;IACD,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,MAAM;QACjB,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,4BAA4B,kBAAkB,CAAC,WAAW,CAAC,GAAG;QACxF,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,eAAe,WAAW,EAAE;KACvD;IACD,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,IAAI,EAAE,OAAO;QACb,SAAS,EAAE,WAAW;QACtB,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,kCAAkC,kBAAkB,CAAC,WAAW,CAAC,EAAE;QAC7F,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,sBAAsB,WAAW,EAAE;KAC9D;CACF,CAAC;AAEF,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAC9B,QAAkB,EAClB,aAAgD;IAEhD,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACrF,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;AACtH,CAAC"}

package/lib/types/portal/unknown-fields.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A misspelled field is the one mistake that otherwise produces a portal that builds and is
+ * quietly wrong, so each is reported.
+ */
+export declare function unknownFieldErrors(data: Record<string, unknown>, known: ReadonlySet<string>, describe: (field: string) => string): string[];

package/lib/types/portal/unknown-fields.js

@@ -0,0 +1,10 @@
+/**
+ * A misspelled field is the one mistake that otherwise produces a portal that builds and is
+ * quietly wrong, so each is reported.
+ */
+export function unknownFieldErrors(data, known, describe) {
+    return Object.keys(data)
+        .filter((field) => !known.has(field))
+        .map(describe);
+}
+//# sourceMappingURL=unknown-fields.js.map

package/lib/types/portal/unknown-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-fields.js","sourceRoot":"","sources":["../../../src/types/portal/unknown-fields.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAA6B,EAC7B,KAA0B,EAC1B,QAAmC;IAEnC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;SACrB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;SACpC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACnB,CAAC"}

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

@@ -1,13 +1,45 @@
-import { DirectoryPath } from "./file/directoryPath.js";
-import { FilePath } from "./file/filePath.js";
+import { Result } from 'neverthrow';
+import { DirectoryPath } from './file/directoryPath.js';
+import { FilePath } from './file/filePath.js';
+/** Emitted even by a failed build, so it never counts as a page. */
+export declare const SHELL_FILE_NAME = "_shell.html";
+export declare const NOT_FOUND_FILE_NAME = "404.html";
+export declare const ZIP_FILE_NAME = "portal.zip";
+/**
+ * Why the finished site did not reach the portal directory. `stagingFailed` leaves the
+ * previous portal as it was; `replaceFailed` happened while it was being swapped out, so
+ * whatever did not make it into place is kept at `stagedAt` for the user to move by hand.
+ */
+export type PortalSaveProblem = {
+    kind: 'stagingFailed';
+    reason: string;
+} | {
+    kind: 'replaceFailed';
+    reason: string;
+    stagedAt: DirectoryPath;
+};
 export declare class PortalContext {
     private readonly portalDirectory;
     private readonly fileService;
     private readonly zipService;
     constructor(portalDirectory: DirectoryPath);
-    private get ZipPath();
-    private get reportPath();
+    private get stagingDirectory();
+    private get buildLogPath();
+    /**
+     * Whether anything is there to overwrite. A staging directory left by a save that could
+     * not finish counts, hidden as it is: it may hold the only complete copy of the site.
+     */
     exists(): Promise<boolean>;
-    save(tempPortalFilePath: FilePath, zipPortal: boolean): Promise<void>;
-    saveError(tempErrorFilePath: FilePath): Promise<FilePath>;
+    /**
+     * Writes the finished site to the portal directory, as files or as a single archive.
+     * The site is staged inside the destination first, so the previous portal is only
+     * touched once the whole new one is on the same volume and what remains is a rename.
+     */
+    save(builtDirectory: DirectoryPath, asZip: boolean): Promise<Result<void, PortalSaveProblem>>;
+    /**
+     * Keeps a failed build's output for the user to inspect after the temp project is gone.
+     * Null when the log itself could not be written.
+     */
+    saveBuildLog(log: string): Promise<FilePath | null>;
+    private addNotFoundPage;
 }