@apimatic/cli 2.0.0-beta.4 → 2.0.0-beta.6

package/portal-template/src/routes/$.tsx

@@ -3,6 +3,7 @@ import { createServerFn } from '@tanstack/react-start';
 import { docs, generated } from '@/lib/source';
 import { source } from '@/lib/source.server';
 import { PortalLayout } from '@/lib/layout';
+import { fullAddress } from '@/lib/base-path';
 import { getPageMarkdownUrl, slugsFromSplat } from '@/lib/shared';
 import { portal } from '@/lib/portal';
 import { absoluteUrl, canonicalLink } from '@/lib/seo';
@@ -129,7 +130,7 @@ function Content({
   const PageBody = page.body;
   const pathname = usePathname();
   // Named, or the popover reads `window.location.href` and sends the reader's query and hash on.
-  const pageUrl = typeof window === 'undefined' ? pathname : new URL(pathname, window.location.origin).toString();
+  const pageUrl = fullAddress(pathname);
 
   return (
     <DocsPage toc={toc} full={page.full}>
@@ -137,7 +138,7 @@ function Content({
       <DocsDescription>{page.description}</DocsDescription>
       <div className="flex flex-row gap-2 items-center border-b -mt-4 pb-6">
         {/* Keyed so a new page starts at "Copy Markdown", not at the last page's result. */}
-        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} base={import.meta.env.BASE_URL} />
+        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} />
         {/* Sends the reader to an external AI vendor, so a portal published under someone
             else's brand can turn it off. */}
         {portal.pageActions ? <ViewOptionsPopover markdownUrl={markdownUrl} pageUrl={pageUrl} /> : null}

package/portal-template/src/routes/__root.tsx

@@ -5,6 +5,7 @@ import { source } from '@/lib/source.server';
 import appCss from '@/styles/app.css?url';
 import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 import SearchDialog from '@/components/search';
+import { withBasePath } from '@/lib/base-path';
 import { portal } from '@/lib/portal';
 
 // The sidebar tree is the same on every page. Loaded here, once, it is written to a single
@@ -15,7 +16,13 @@ const loadPageTree = createServerFn({ method: 'GET' })
 
 // Without one the browser tab shows the blank-document icon on every page.
 const iconLinks = portal.favicon
-  ? [{ rel: 'icon', href: portal.favicon.url, ...(portal.favicon.type ? { type: portal.favicon.type } : {}) }]
+  ? [
+      {
+        rel: 'icon',
+        href: withBasePath(portal.favicon.url),
+        ...(portal.favicon.type ? { type: portal.favicon.type } : {})
+      }
+    ]
   : [];
 
 // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no

package/portal-template/src/routes/api/search[.]json.ts

@@ -1,9 +1,30 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { source } from '@/lib/source.server';
+import { withoutImages } from '@/lib/search-content';
+import { type PortalPage, source } from '@/lib/source.server';
 import { createFromSource } from 'fumadocs-core/search/server';
 
-const server = createFromSource(source, { language: 'english' });
+// Fumadocs indexes a reference page's description as written, so results show its images, without the path.
+const server = createFromSource(
+  { ...source, getPages: (language?: string) => source.getPages(language).map(searchable) },
+  { language: 'english' }
+);
 
 export const Route = createFileRoute('/api/search.json')({
   server: { handlers: { GET: () => server.staticGET() } }
 });
+
+/** A reference page as Fumadocs indexes a page of its own: without images. */
+function searchable(page: PortalPage): PortalPage {
+  if (page.type !== 'openapi') return page;
+  const { description, structuredData } = page.data;
+  const contents = structuredData.contents.map((item) => ({ ...item, content: withoutImages(item.content) }));
+  // Both alike, or Fumadocs no longer finds the description among the contents and indexes it a second time.
+  return {
+    ...page,
+    data: {
+      ...page.data,
+      description: description && withoutImages(description),
+      structuredData: { ...structuredData, contents }
+    }
+  };
+}

package/portal-template/src/routes/oauth.callback.tsx

@@ -0,0 +1,54 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { useEffect, useState } from 'react';
+import { AuthorizationFailure } from '@/components/authorization-failure';
+import { baseOptions } from '@/lib/layout.shared';
+import { forgetStartingPage, oauthCallback, type OAuthCallback, type OAuthCallbackFailure } from '@/lib/oauth-callback';
+import { portal } from '@/lib/portal';
+
+// Published portals are static, so this page does in the browser what Fumadocs'
+// `createOAuthHandler()` route does on a server.
+export const Route = createFileRoute('/oauth/callback')({
+  head: () => ({ meta: [{ title: `Authorization | ${portal.name}` }, { name: 'robots', content: 'noindex' }] }),
+  component: OAuthCallbackPage
+});
+
+let completion: OAuthCallback | undefined;
+
+/**
+ * Reading the cookie and sending the browser on can each happen only once per page load, not
+ * once per mount: the StrictMode `portal serve` runs under mounts the page twice, and the second
+ * mount would find the cookie gone. The answer is kept, so a later mount in the same load, such
+ * as Back after leaving through the header, shows the same outcome. Every arrival from a provider
+ * is a new load.
+ */
+function completeAuthorization(): OAuthCallback {
+  if (completion === undefined) {
+    completion = oauthCallback(document.cookie, window.location);
+    forgetStartingPage();
+    if (completion.kind === 'return') window.location.replace(completion.url);
+  }
+  return completion;
+}
+
+function OAuthCallbackPage() {
+  // Null until the effect has read the cookie, which the prerendered page cannot.
+  const [failure, setFailure] = useState<OAuthCallbackFailure | null>(null);
+
+  useEffect(() => {
+    const callback = completeAuthorization();
+    if (callback.kind !== 'return') setFailure(callback);
+  }, []);
+
+  return (
+    <HomeLayout {...baseOptions()}>
+      <div className="flex flex-col px-8 justify-center flex-1 text-center items-center gap-4">
+        {failure === null ? (
+          <p className="text-fd-muted-foreground">Completing authorization…</p>
+        ) : (
+          <AuthorizationFailure failure={failure} />
+        )}
+      </div>
+    </HomeLayout>
+  );
+}

package/portal-template/static-functions-base.ts

@@ -0,0 +1,41 @@
+import type { Plugin } from 'vite';
+import { withBasePath } from './src/lib/base-path';
+
+/** The package whose browser half fetches a prerendered server function's result. */
+const PACKAGE = /[\\/]@tanstack[\\/]start-static-server-functions[\\/]/;
+
+/** Where it fetches that result from, opening backtick included so nothing else naming the folder matches. */
+export const CACHE_ADDRESS = '`/__tsr/staticServerFnCache/';
+
+/** Puts the browser's fetch of prerendered page data under the base, until TanStack/router#6152 does it itself. */
+export function staticFunctionsBase(): Plugin {
+  let base = '/';
+  let found = false;
+  return {
+    name: 'apimatic:static-functions-base',
+    apply: 'build',
+    enforce: 'pre',
+    // The server writes the files under the output directory, which the host already serves at the base.
+    applyToEnvironment: (environment) => environment.name === 'client',
+    configResolved(config) {
+      base = config.base;
+    },
+    transform: {
+      filter: { id: PACKAGE, code: CACHE_ADDRESS },
+      handler(code) {
+        // Found at the root too, where the replacement is the address itself.
+        found = true;
+        return code.replaceAll(CACHE_ADDRESS, '`' + withBasePath(CACHE_ADDRESS.slice(1), base));
+      }
+    },
+    // An upgrade that moves the address fails the build, rather than every link in the portal.
+    buildEnd(error) {
+      if (error === undefined && !found) {
+        this.error(
+          `No module of @tanstack/start-static-server-functions holds ${CACHE_ADDRESS}, so a portal ` +
+            'served under a path could not load the pages its links lead to. See portal-template/static-functions-base.ts.'
+        );
+      }
+    }
+  };
+}

package/portal-template/vite.config.ts

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import react from '@vitejs/plugin-react';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
-import { defineConfig } from 'vite';
+import { defineConfig, searchForWorkspaceRoot } from 'vite';
 import tailwindcss from '@tailwindcss/vite';
 import { fumadocsMdx } from 'fumadocs-mdx/vite';
 import { dependencyDirectories } from './dependency-directories.ts';
@@ -10,25 +10,34 @@ import { generatedPagesReload } from './generated-pages-reload.ts';
 import { readBuildPaths, readPortalIdentity } from './portal-config.ts';
 import { prerenderPages } from './prerender-pages.ts';
 import { specReload } from './spec-reload.ts';
+import { remarkImageReferences } from './src/lib/remark-image-references.ts';
+import { staticFunctionsBase } from './static-functions-base.ts';
 
 export default defineConfig(async () => {
   const [paths, identity] = await Promise.all([readBuildPaths(), readPortalIdentity()]);
   const pages = await prerenderPages(paths, identity.siteUrl);
   const publicDir: string | false = paths.staticDir ?? false;
-  const projectDirectory = fileURLToPath(new URL('.', import.meta.url));
+  const portalProjectDirectory = fileURLToPath(new URL('.', import.meta.url));
 
   return {
+    // TanStack Start derives the router's basepath and every asset URL from it.
+    base: paths.base,
     publicDir,
     plugins: [
       generatedPagesReload(),
       downloads(paths.downloadsDir),
+      staticFunctionsBase(),
       // `/images/logo.png` is read from the static directory, and a remote image is never fetched for its size.
       fumadocsMdx({
         globalOptions: {
-          mdxOptions: { remarkImageOptions: { publicDir: publicDir || undefined, external: false } }
+          mdxOptions: {
+            remarkImageOptions: { publicDir: publicDir || undefined, external: false },
+            // A function, so it runs ahead of the preset's own plugins, `remarkImage` among them.
+            remarkPlugins: (plugins) => [remarkImageReferences, ...plugins]
+          }
         }
       }),
-      specReload(paths.specs),
+      specReload(paths.specDir),
       tailwindcss(),
       tanstackStart({
         // Without a mask path the shell is rendered at "/" and no index.html is written;
@@ -57,13 +66,11 @@ export default defineConfig(async () => {
     // listens on `::1` alone, a connect that stalls under load falls back to 127.0.0.1 and is
     // refused, failing the build; binding IPv4 leaves the fetch a single address to reach.
     preview: { host: '127.0.0.1' },
-    // Spelled out because the default, the project alone, misses the CLI installation the
-    // dependencies are linked from, and the static directory pages import images from.
     server: {
       fs: {
         allow: [
-          projectDirectory,
-          ...dependencyDirectories(projectDirectory),
+          searchForWorkspaceRoot(portalProjectDirectory),
+          ...dependencyDirectories(portalProjectDirectory),
           ...(paths.staticDir === null ? [] : [paths.staticDir])
         ]
       }