@apimatic/cli 1.5.0 → 2.0.0-beta.2

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@apimatic/cli",
     "description": "The official CLI for APIMatic.",
-    "version": "1.5.0",
+    "version": "2.0.0-beta.2",
     "author": "APIMatic",
     "bin": {
         "apimatic": "./bin/run.js"
@@ -14,13 +14,16 @@
         "access": "public"
     },
     "engines": {
-        "node": ">=20.0.0"
+        "node": ">=24.0.0"
     },
     "packageManager": "pnpm@11.0.8",
     "files": [
         "./bin",
         "./lib",
-        "/oclif.manifest.json"
+        "./portal-template",
+        "./portal-pages",
+        "/oclif.manifest.json",
+        "/apimatic.schema.json"
     ],
     "repository": "git://github.com/apimatic/apimatic-cli.git",
     "homepage": "https://docs.apimatic.io/apimatic-cli/intro-and-install/",
@@ -41,9 +44,10 @@
         "build:watch": "rimraf oclif.manifest.json && tsc --watch",
         "apimatic": "node ./bin/run.js",
         "prepack": "oclif manifest",
-        "posttest": "eslint . --ext .ts",
-        "prettier": "prettier \"src/**/*.{js,ts}\"",
-        "format": "prettier --write \"src/**/*.{js,ts}\"",
+        "pretest": "tsc -p test/tsconfig.json",
+        "posttest": "eslint .",
+        "prettier": "prettier \"src/**/*.{js,ts}\" \"portal-template/**/*.{ts,tsx}\"",
+        "format": "prettier --write \"src/**/*.{js,ts}\" \"portal-template/**/*.{ts,tsx}\"",
         "lint": "eslint \"src/**/*.{js,ts}\"",
         "lint:fix": "eslint --fix \"src/**/*.{js,ts}\" --quiet",
         "readme": "oclif readme",
@@ -53,38 +57,58 @@
         "@apimatic/sdk": "0.2.0-alpha.10",
         "@clack/core": "1.0.0-alpha.1",
         "@clack/prompts": "1.0.0-alpha.1",
+        "@fontsource-variable/geist": "5.3.0",
+        "@fontsource-variable/geist-mono": "5.3.0",
+        "@fumadocs/api-docs": "0.2.8",
         "@oclif/core": "^4.2.8",
         "@oclif/plugin-autocomplete": "^3.2.24",
         "@oclif/plugin-help": "^6.2.26",
+        "@scalar/json-magic": "0.13.4",
+        "@tailwindcss/vite": "4.3.3",
+        "@tanstack/react-router": "1.170.33",
+        "@tanstack/react-start": "1.168.50",
+        "@tanstack/start-static-server-functions": "1.167.33",
+        "@vitejs/plugin-react": "6.1.1",
         "adm-zip": "^0.5.17",
         "ansis": "^3.17.0",
         "async-mutex": "^0.5.0",
         "axios": "^1.8.1",
-        "chokidar": "^3.6.0",
-        "connect-livereload": "^0.6.1",
         "execa": "^9.6.0",
-        "express": "^4.17.1",
         "fast-levenshtein": "^3.0.0",
         "form-data": "^4.0.2",
         "fs-extra": "^11.3.0",
+        "fumadocs-core": "16.15.15",
+        "fumadocs-mdx": "15.4.0",
+        "fumadocs-openapi": "11.4.1",
+        "fumadocs-ui": "16.15.15",
         "get-port": "^7.1.0",
         "is-in-ci": "^2.0.0",
         "isomorphic-git": "^1.37.2",
-        "livereload": "^0.9.3",
+        "lucide-react": "1.47.0",
+        "mustache": "^4.2.0",
         "neverthrow": "^8.2.0",
         "open": "^8.4.0",
         "picocolors": "^1.1.1",
         "prettier": "^2.8.8",
+        "react": "19.2.8",
+        "react-dom": "19.2.8",
+        "rehype-raw": "7.0.0",
+        "remark": "15.0.1",
+        "remark-mdx": "3.1.1",
+        "semver": "^7.8.0",
+        "shiki": "4.4.3",
         "striptags": "^3.2.0",
+        "tailwindcss": "4.3.3",
         "tmp-promise": "^3.0.3",
         "tslib": "^2.8.1",
         "uuid": "^11.1.0",
+        "vite": "8.2.2",
         "yaml": "^2.8.0",
         "yazl": "^3.3.1"
     },
     "devDependencies": {
         "@commitlint/cli": "^20.5.0",
-        "@commitlint/config-conventional": "^15.0.0",
+        "@commitlint/config-conventional": "^20.5.3",
         "@eslint/js": "^9.34.0",
         "@oclif/test": "^4.1.13",
         "@semantic-release/changelog": "^6.0.3",
@@ -92,21 +116,23 @@
         "@types/adm-zip": "^0.5.8",
         "@types/base-64": "^1.0.0",
         "@types/chai": "^4.3.20",
-        "@types/connect-livereload": "^0.5.32",
-        "@types/express": "^4.17.23",
         "@types/fast-levenshtein": "^0.0.4",
         "@types/fs-extra": "^9.0.13",
-        "@types/livereload": "^0.9.5",
-        "@types/mocha": "^5.2.7",
-        "@types/mock-fs": "^4.13.4",
-        "@types/node": "^20.17.50",
+        "@types/mocha": "^10.0.10",
+        "@types/mustache": "^4.2.6",
+        "@types/node": "^24.13.4",
         "@types/prettier": "^2.7.3",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "@types/semver": "^7.8.0",
         "@types/sinon": "^17.0.4",
         "@types/treeify": "^1.0.3",
         "@types/unzipper": "^0.10.4",
         "@types/yazl": "^3.3.0",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
         "@typescript-eslint/parser": "^8.0.0",
+        "@typescript/native": "npm:typescript@^7.0.2",
+        "ajv": "^8.20.0",
         "chai": "^4.5.0",
         "eslint": "^9.21.0",
         "eslint-config-prettier": "^8.3.0",
@@ -114,7 +140,6 @@
         "husky": "^7.0.4",
         "lint-staged": "^11.2.6",
         "mocha": "^11.7.1",
-        "mock-fs": "^5.5.0",
         "nock": "^14.0.4",
         "nyc": "^17.1.0",
         "oclif": "^4.17.34",
@@ -123,9 +148,8 @@
         "simple-git": "^3.36.0",
         "sinon": "^21.0.0",
         "string-argv": "^0.3.1",
-        "ts-node": "^10.9.2",
         "tsx": "^4.20.3",
-        "typescript": "^5.2.2"
+        "typescript": "npm:@typescript/typescript6@^6.0.2"
     },
     "oclif": {
         "commands": "./lib/commands",
@@ -133,6 +157,7 @@
         "bin": "apimatic",
         "description": "The official CLI for APIMatic. \nTo get started with APIMatic's CLI using a step by step wizard, run 'apimatic quickstart'.",
         "hooks": {
+            "init": "./lib/hooks/node-version",
             "command_not_found": "./lib/hooks/not-found"
         },
         "plugins": [
@@ -150,7 +175,7 @@
                 "description": "Generate context plugins that teach AI coding assistants to use your SDKs."
             },
             "portal": {
-                "description": "Generate, download and serve an API Documentation portal for your APIs."
+                "description": "Build and serve an API Documentation portal for your APIs."
             },
             "sdk": {
                 "description": "Generate and publish SDKs for your APIs in multiple languages."
@@ -160,15 +185,12 @@
             },
             "publishing:profile": {
                 "description": "Manage publishing profiles."
-            },
-            "portal:toc": {
-                "description": "Generate a Table of Contents (TOC) file for your API documentation portal."
             }
         },
         "topicSeparator": " "
     },
     "lint-staged": {
         "*.js": "eslint --cache --fix",
-        "*.{js,ts}": "prettier --write"
+        "*.{js,ts,tsx}": "prettier --write"
     }
 }

package/portal-pages/context-plugin.mdx

@@ -0,0 +1,26 @@
+---
+title: "Context Plugin"
+description: "Give your AI coding assistant working knowledge of this API's SDKs."
+---
+
+The context plugin teaches your AI coding assistant how to use this API's SDKs, so the code it writes for you calls the API the way the SDKs are meant to be used.
+
+## Install
+
+<PluginInstall path="{{installPath}}" />
+
+## What it does
+
+Once the plugin is installed, describe what you want to build and your assistant works from the SDK for your language: how to install it and create a client, how to authenticate, and which methods and types to use for each call. You spend less time correcting code written from guesses about the API.
+
+## Supported languages
+
+<PluginLanguages>
+{{#languages}}
+<PluginLanguage language="{{language}}" name="{{name}}" />
+{{/languages}}
+</PluginLanguages>
+
+## Supported platforms
+
+<PluginPlatforms />

package/portal-pages/sdk.mdx

@@ -0,0 +1,8 @@
+---
+title: "{{name}} SDK"
+description: "Install and start using the {{name}} SDK."
+---
+
+<SdkActions download="{{download}}" source="{{source}}" packageUrl="{{packageUrl}}" registry="{{registry}}" />
+
+<include>{{docs}}</include>

package/portal-pages/sdks.mdx

@@ -0,0 +1,11 @@
+---
+title: "SDKs"
+description: "Client libraries for this API."
+full: true
+---
+
+<SdkCards>
+{{#sdks}}
+<SdkCard language="{{language}}" name="{{name}}" page="{{page}}" download="{{download}}" source="{{source}}" install="{{install}}" packageUrl="{{packageUrl}}" registry="{{registry}}" />
+{{/sdks}}
+</SdkCards>

package/portal-template/NOTICE

@@ -0,0 +1,37 @@
+This directory is the build project the APIMatic CLI copies into a temporary
+directory to generate a documentation portal. It is distributed under the MIT
+licence, with the rest of @apimatic/cli.
+
+It is derived from the Fumadocs and TanStack Start starter templates, and at
+build time it runs against the packages below. Each is MIT licensed and carries
+its own copyright:
+
+  Fumadocs (fumadocs-core, fumadocs-ui, fumadocs-mdx, fumadocs-openapi)
+    Copyright (c) 2023 Fuma Nama
+
+  TanStack Start and TanStack Router (@tanstack/react-start, @tanstack/react-router,
+  @tanstack/start-static-server-functions)
+    Copyright (c) 2021-present Tanner Linsley
+
+  Shiki, Tailwind CSS, React, Vite and rehype-raw are likewise MIT licensed; see
+  their own packages for the full notices.
+
+The SDK and context plugin pages draw these marks, copied into
+src/components/logos.tsx:
+
+  The C#, Python and TypeScript logos, from Devicon 2.17.0
+    Copyright (c) 2015 konpa, MIT licensed
+    https://github.com/devicons/devicon
+
+  The Claude, Cursor and GitHub Copilot logos, from Simple Icons 16.32.0
+    CC0 1.0 Universal, https://github.com/simple-icons/simple-icons
+
+  Each mark remains the trademark of its owner, and is shown to name the
+  language or tool it stands for.
+
+The generated portal also bundles the Geist and Geist Mono typefaces, from the
+Fontsource packages @fontsource-variable/geist and @fontsource-variable/geist-mono.
+They are licensed under the SIL Open Font License 1.1, not MIT:
+
+  Geist and Geist Mono
+    Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)

package/portal-template/downloads.ts

@@ -0,0 +1,41 @@
+import { createReadStream } from 'node:fs';
+import { cp, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import type { Plugin } from 'vite';
+
+/** Where the site offers the downloads: a name the user's static directory is not expected to use. */
+export const DOWNLOADS_ADDRESS = '__downloads';
+
+/**
+ * Adds the SDKs and the context plugin the CLI downloaded to the site, which Vite's one
+ * `publicDir` cannot, since that is the user's static directory.
+ */
+export function downloads(directory: string | null): Plugin {
+  return {
+    name: 'apimatic:downloads',
+    async configureServer(server) {
+      if (directory === null) return;
+      const files = await filesByAddress(directory);
+      server.middlewares.use((request, response, next) => {
+        const file = files.get(decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname));
+        if (file === undefined) return next();
+        response.setHeader('Content-Type', 'application/zip');
+        createReadStream(file).pipe(response);
+      });
+    },
+    async writeBundle(options) {
+      if (directory === null || this.environment.name !== 'client' || options.dir === undefined) return;
+      await cp(directory, path.join(options.dir, DOWNLOADS_ADDRESS), { recursive: true });
+    }
+  };
+}
+
+async function filesByAddress(directory: string): Promise<Map<string, string>> {
+  const entries = await readdir(directory, { recursive: true, withFileTypes: true });
+  const files = new Map<string, string>();
+  for (const entry of entries.filter((candidate) => candidate.isFile())) {
+    const file = path.join(entry.parentPath, entry.name);
+    files.set(`/${DOWNLOADS_ADDRESS}/${path.relative(directory, file).split(path.sep).join('/')}`, file);
+  }
+  return files;
+}

package/portal-template/generated-pages-reload.ts

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import type { Plugin } from 'vite';
+
+/** Where the CLI writes the pages it generates, as `src/lib/source.ts` names it. */
+const GENERATED_DIRECTORY = 'generated';
+
+/** The module that declares the collections, and so holds the glob of their files. */
+const SOURCE_MODULE = 'src/lib/source.ts';
+
+/**
+ * The files the collection reads: its pages and their `nav.json`. The CLI writes each one
+ * beside itself under a temporary name and renames it over, and those names are left out.
+ */
+const COLLECTED_FILE = /\.(md|mdx|json)$/;
+
+/**
+ * fumadocs-mdx expands each collection into a glob of imports when it transforms
+ * `src/lib/source.ts`, and under `vite dev` it does not expand it again when a file is added
+ * or removed: an added page never appears, and a removed one fails every request until the
+ * server restarts. `portal serve` adds and removes generated pages as `apimatic.json` changes,
+ * so an add or remove there is passed on as an edit to that module, which Vite transforms again.
+ */
+export function generatedPagesReload(): Plugin {
+  return {
+    name: 'apimatic:generated-pages-reload',
+    apply: 'serve',
+    configureServer(server) {
+      const directory = path.resolve(server.config.root, GENERATED_DIRECTORY);
+      const sourceModule = path.resolve(server.config.root, SOURCE_MODULE);
+      const reload = () => server.watcher.emit('change', sourceModule);
+      const onFileAddedOrRemoved = (file: string) => {
+        if (isInside(directory, file) && COLLECTED_FILE.test(file)) {
+          reload();
+        }
+      };
+      server.watcher.on('add', onFileAddedOrRemoved);
+      server.watcher.on('unlink', onFileAddedOrRemoved);
+      server.watcher.on('unlinkDir', (folder: string) => {
+        if (isInside(directory, folder)) {
+          reload();
+        }
+      });
+    }
+  };
+}
+
+// `path.relative` compares case-insensitively on Windows, as the file system there does.
+function isInside(directory: string, file: string): boolean {
+  const relative = path.relative(directory, path.resolve(file));
+  return relative.length > 0 && relative.split(path.sep)[0] !== '..' && !path.isAbsolute(relative);
+}

package/portal-template/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "apimatic-portal",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "description": "Build project for the API documentation portal generated by the APIMatic CLI. Dependencies are provided by the CLI at build time.",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite dev"
+  }
+}

package/portal-template/portal-config.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import type { Portal } from './src/lib/portal-types';
+
+/** Written by the CLI next to this file before every build or dev-server start. */
+export interface BuildPaths {
+  /** Section slug -> absolute path of an OpenAPI document. */
+  specs: Record<string, string>;
+  /** Absolute path of the code samples, keyed by path then method; null when there are none. */
+  codeSamples: string | null;
+  /** Absolute. Always exists, and may be empty. */
+  contentDir: string;
+  /** Absolute, inside this project: the pages the CLI generates, which `src/lib/source.ts` compiles. */
+  generatedDir: string;
+  staticDir: string | null;
+  /** Absolute, inside this project: the SDKs and the context plugin, laid out as the site serves them under `/__downloads/`. */
+  downloadsDir: string | null;
+}
+
+export async function readBuildPaths(): Promise<BuildPaths> {
+  return (await readJson('./portal.config.json')) as BuildPaths;
+}
+
+/** The part of what the browser is told that the build set-up reads too. */
+export type BuildIdentity = Pick<Portal, 'siteUrl'>;
+
+export async function readPortalIdentity(): Promise<BuildIdentity> {
+  return (await readJson('./portal.identity.json')) as BuildIdentity;
+}
+
+async function readJson(relative: string): Promise<unknown> {
+  return JSON.parse(await readFile(new URL(relative, import.meta.url), 'utf8'));
+}

package/portal-template/prerender-pages.ts

@@ -0,0 +1,81 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getSlugs, loader } from 'fumadocs-core/source';
+import type { BuildPaths } from './portal-config.ts';
+import { openApiSection } from './src/lib/openapi-section.server';
+
+const CONTENT_EXTENSIONS = new Set(['.md', '.mdx']);
+
+/** Passed over by Vite's `import.meta.glob`, which the content collection is read through. */
+const isSkippedByGlob = (segment: string) => segment.startsWith('.') || segment === 'node_modules';
+
+/**
+ * Every URL the static build has to emit. TanStack Start's crawler misses links inside
+ * collapsed sidebar folders and never sees the `.md` URLs the page actions fetch, so
+ * the list is computed here from the same sources the site is built from.
+ */
+export async function prerenderPages(config: BuildPaths, siteUrl: string | null): Promise<{ path: string }[]> {
+  const urls = new Set<string>(['/', '/api/search.json', '/llms.txt', '/llms-full.txt']);
+  // Both need absolute URLs, so they are only emitted for a portal that declares its address.
+  if (siteUrl) {
+    urls.add('/sitemap.xml');
+    urls.add('/robots.txt');
+  }
+
+  for (const url of await contentUrls(config.contentDir)) urls.add(url);
+  // The CLI keeps the user's pages away from the generated ones' addresses, so the two
+  // directories never collide and can be listed apart.
+  for (const url of await contentUrls(config.generatedDir)) urls.add(url);
+  for (const url of await openApiUrls(config.specs)) urls.add(url);
+
+  // The copy is load-bearing, not redundant: this loop adds to `urls`, and a `Set` visits
+  // entries added during iteration, so iterating `urls` itself would suffix the `.md` URLs it
+  // creates in turn -- `/guides.md.md` and on, never terminating.
+  for (const url of [...urls]) {
+    if (url === '/') urls.add('/index.md');
+    else if (!/\.(txt|xml|json)$/.test(url)) urls.add(`${url}.md`);
+  }
+
+  return [...urls].map((url) => ({ path: url }));
+}
+
+async function contentUrls(contentDir: string): Promise<string[]> {
+  const entries = await readdir(contentDir, { recursive: true, withFileTypes: true }).catch(() => []);
+
+  const files = entries
+    .filter((entry) => entry.isFile() && CONTENT_EXTENSIONS.has(path.extname(entry.name)))
+    .map((entry) => path.relative(contentDir, path.join(entry.parentPath, entry.name)).split(path.sep).join('/'))
+    .filter((file) => !file.split('/').some(isSkippedByGlob))
+    .map((file) => {
+      // The content source's own slug rules, not a second implementation: "(group)" folders
+      // drop out, "index" collapses into its parent.
+      return { slugs: getSlugs(file), isIndex: path.basename(file, path.extname(file)) === 'index' };
+    });
+
+  // `guides.md` and `guides/index.md` both collapse to "guides". The content source settles
+  // that by taking the non-index files first and appending "index" to the loser, so the same
+  // order has to hold here or the page it moves to /guides/index is never written.
+  const taken = new Set<string>();
+  const claim = (slugs: string[]): string => {
+    const key = slugs.join('/');
+    taken.add(key);
+    return '/' + key;
+  };
+
+  const urls = files.filter((file) => !file.isIndex).map((file) => claim(file.slugs));
+  for (const file of files.filter((file) => file.isIndex)) {
+    urls.push(claim(taken.has(file.slugs.join('/')) ? [...file.slugs, 'index'] : file.slugs));
+  }
+  return urls;
+}
+
+// Through the same sections as the site, so an internal operation gets no page here either.
+async function openApiUrls(specs: Record<string, string>): Promise<string[]> {
+  const sources = Object.fromEntries(
+    await Promise.all(Object.entries(specs).map(async ([id, file]) => [id, await openApiSection(id, file, null)]))
+  );
+  if (Object.keys(sources).length === 0) return [];
+  return loader(sources, { baseUrl: '/' })
+    .getPages()
+    .map((page) => page.url);
+}

package/portal-template/spec-reload.ts

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import type { Plugin } from 'vite';
+
+/**
+ * Reloads the preview when a file beside a specification changes. The specifications are read
+ * at run time rather than imported, so Vite's module graph never learns of them, and the
+ * reference pages are built once per server module evaluation.
+ */
+export function specReload(specs: Record<string, string>): Plugin {
+  const directories = [...new Set(Object.values(specs).map((file) => path.posix.dirname(file)))];
+  const isInSpecDirectory = (file: string) => directories.some((directory) => file.startsWith(`${directory}/`));
+
+  return {
+    name: 'apimatic:spec-reload',
+    apply: 'serve',
+    configureServer(server) {
+      server.watcher.add(directories);
+    },
+    // Sent to each environment: the server runner re-evaluates every module, the browser reloads.
+    hotUpdate({ file }) {
+      if (!isInSpecDirectory(file)) return;
+      this.environment.hot.send({ type: 'full-reload' });
+      return [];
+    }
+  };
+}

package/portal-template/src/components/api-page.tsx

@@ -0,0 +1,15 @@
+import { createOpenAPIPage } from 'fumadocs-openapi/ui';
+import { createCodeUsageGeneratorRegistry } from 'fumadocs-openapi/requests/generators';
+import { mediaAdapters } from '@/lib/media-adapters';
+import { CodeBlock } from './code-block';
+import { renderExampleLayout } from './example-layout';
+import { renderUsageTabs } from './usage-tabs';
+
+export const OpenAPIPage = createOpenAPIPage({
+  // Without a registry of its own, Fumadocs registers and bundles every request generator it has.
+  codeUsages: createCodeUsageGeneratorRegistry(),
+  generateTypeScriptDefinitions: false,
+  components: { CodeBlock },
+  content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs },
+  mediaAdapters
+});

package/portal-template/src/components/code-block.tsx

@@ -0,0 +1,9 @@
+import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock.core';
+import { useRenderContext } from 'fumadocs-openapi/ui';
+
+// Fumadocs passes `JSON.stringify(example.value)`, which is undefined for an example with no `value`.
+export function CodeBlock({ lang, code }: Readonly<{ lang: string; code: string | undefined }>) {
+  const { shiki, shikiOptions } = useRenderContext();
+  if (code === undefined) return null;
+  return <DynamicCodeBlock lang={lang} code={code} highlighter={() => shiki.getOrInit()} options={shikiOptions} />;
+}

package/portal-template/src/components/command-block.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import { asMarkdown } from 'fumadocs-core/server';
+import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';
+import { CODE_BLOCK_TITLES } from '@/lib/code-titles';
+
+interface CommandBlockProps {
+  command: string;
+  /** One line that truncates, for a card; the full command is still what the button copies. */
+  compact?: boolean;
+}
+
+// Centred on the one line, where the block's own placement pins the button to the top corner.
+function CentredActions({ children }: Readonly<{ children?: ReactNode }>) {
+  return <div className="absolute inset-y-0 end-1.5 z-2 flex items-center text-fd-muted-foreground">{children}</div>;
+}
+
+/** One shell command in a copyable block: an MDX page has no highlighter to hand, so it is plain. */
+export function CommandBlock({ command, compact = false }: Readonly<CommandBlockProps>) {
+  if (asMarkdown()) {
+    return `\`\`\`bash\n${command}\n\`\`\``;
+  }
+  if (!compact) {
+    return (
+      <CodeBlock title={CODE_BLOCK_TITLES.shellscript}>
+        <Pre>
+          <code>
+            {/* A highlighted block's lines carry this class, which is what the block pads. */}
+            <span className="line">{command}</span>
+          </code>
+        </Pre>
+      </CodeBlock>
+    );
+  }
+  return (
+    <CodeBlock
+      className="my-0 rounded-lg bg-fd-secondary shadow-none"
+      viewportProps={{ className: 'py-2 text-xs' }}
+      Actions={CentredActions}
+    >
+      <Pre className="w-full">
+        <code>
+          {/* The block pads a line only as far as the button's edge, so a cut-off command would run up to it. */}
+          <span className="line truncate [--padding-right:calc(var(--spacing)*10)]" title={command}>
+            {command}
+          </span>
+        </code>
+      </Pre>
+    </CodeBlock>
+  );
+}