pulumi-package-docs 0.8.0 → 0.9.1

package/README.md

@@ -11,13 +11,27 @@ npx pulumi-package-docs
 This serves docs for the Pulumi project in your current directory. Options:
 
 ```bash
-pulumi-package-docs [options]
+pulumi-package-docs [command] [options]
 
+Commands:
+  serve              Serve the docs (default)
+  static             Generate a static site to publish (GitHub/GitLab Pages)
+
+Options:
   -d, --dir <path>   Pulumi project directory to inspect (default: current directory)
+  -h, --help         Show this help message
+
+serve options:
   -p, --port <port>  Port to serve on (default: 3000)
   --host             Expose the server on your network
   --open             Open the docs in your default browser once ready
-  -h, --help         Show this help message
+  --stdio            Run as an MCP server over stdio instead of serving the docs site
+
+static options:
+  -o, --out <path>   Directory to write the site to (default: <dir>/pulumi-package-docs-site)
+  -b, --base <path>  Base URL path the site is served from, e.g. /my-repo/ for a
+                     GitHub/GitLab Pages project site (default: /)
+  -f, --force        Overwrite --out even if it holds files we didn't generate
 ```
 
 Requires the `pulumi` CLI to be installed and on `PATH`; it's used to fetch each provider's schema (`pulumi package get-schema`). If a schema was fetched successfully before, it's cached and reused if a later CLI call fails.
@@ -37,9 +51,81 @@ On macOS or Linux, it's also available via Homebrew:
 brew install pierskarsenbarg/tap/pulumi-package-docs
 ```
 
+## Static site (GitHub Pages / GitLab Pages)
+
+`pulumi-package-docs static` renders the same docs to a folder of plain HTML,
+so a project's provider docs can live on GitHub Pages, GitLab Pages, or any
+other static host instead of only on a developer's machine:
+
+```bash
+npx pulumi-package-docs static                       # -> ./pulumi-package-docs-site
+npx pulumi-package-docs static --out ./site \
+  --base /my-repo/                                   # for https://<owner>.github.io/my-repo/
+```
+
+Every provider, resource and function gets its own prerendered page, with the
+project's `Pulumi.yaml` deciding what's in the site — the generator crawls its
+own output, so nothing needs listing up front. The pages ship without the
+client bundle: links are ordinary links and each page stands on its own, which
+keeps a large provider's schema out of the pages that don't need it. The
+`pulumi` CLI is needed to generate the site (same as serving it), but not to
+host it.
+
+`--base` is the path the site is served from, and it has to match: a
+GitHub/GitLab Pages _project_ site lives under `/<repo>/`, while a user/org
+site (or a custom domain) lives at `/`, where `--base` can be left off. The
+output directory is rebuilt on each run, and a non-empty directory that wasn't
+generated by this tool is left alone unless you pass `--force`.
+
+Preview the result with any static file server:
+
+```bash
+npx serve ./site
+```
+
+Ready-to-copy CI config lives in [`examples/`](examples): [GitHub
+Actions](examples/github-pages.yml) and [GitLab
+CI](examples/gitlab-ci.yml). Both install the `pulumi` CLI (the schemas come
+from it), run the generator, and publish the output — note that GitLab Pages
+only publishes a directory called `public`.
+
+The standalone binaries can't generate a static site (they carry no build
+toolchain); use `npx pulumi-package-docs static` for that.
+
 ## MCP
 
-The server also exposes an [MCP](https://modelcontextprotocol.io) endpoint at `/mcp` (Streamable HTTP), so a coding agent can look up the same local provider docs without browsing the site. Point an MCP client at `http://localhost:3000/mcp` (e.g. in Claude Code, `claude mcp add --transport http pulumi-package-docs http://localhost:3000/mcp`). Tools:
+The same local provider docs are available to coding agents over [MCP](https://modelcontextprotocol.io), via either transport.
+
+**Streamable HTTP**, while the docs site is running: the server exposes an MCP endpoint at `/mcp`, so point an MCP client at `http://localhost:3000/mcp` (e.g. in Claude Code, `claude mcp add --transport http pulumi-package-docs http://localhost:3000/mcp`).
+
+**stdio**, for clients that spawn a server process instead of connecting to a URL: run with `--stdio` and no docs site is started at all — the process speaks MCP on stdin/stdout and exits with the client.
+
+```bash
+claude mcp add pulumi-package-docs -- npx -y pulumi-package-docs --stdio --dir /path/to/pulumi/project
+```
+
+Or, in an MCP client's JSON config:
+
+```json
+{
+  "mcpServers": {
+    "pulumi-package-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "pulumi-package-docs",
+        "--stdio",
+        "--dir",
+        "/path/to/pulumi/project"
+      ]
+    }
+  }
+}
+```
+
+`--dir` defaults to the process's working directory, so it can be omitted when the client launches the server from the Pulumi project itself. The standalone binary works the same way — use its path in place of `npx -y pulumi-package-docs`.
+
+Both transports serve the same tools:
 
 - `list_providers` — the local providers declared in `Pulumi.yaml`, with resource/function counts and schema load status.
 - `list_resources` / `list_functions` — a provider's resource or function tokens, with a one-line summary and deprecation status for each.
@@ -73,7 +159,15 @@ Build the production app with:
 npm run build
 ```
 
-`bin/cli.js` is the `npx` entry point: it serves the production build with `vite preview` if one exists (`npm run build` first), otherwise falls back to `vite dev`. `bin/cli-bun.js` is a separate entry point used to build the standalone Bun executables (see above); it serves the built SSR handler directly with `Bun.serve` instead of shelling out to Vite. Build one locally with:
+Build a static site from the same sources (`VITE_STATIC_DOCS=true` switches the
+app into its no-hydration, prerendered mode, and `PULUMI_DOCS_BASE` sets the
+path it's served from):
+
+```bash
+node bin/cli.js static --dir /path/to/pulumi/project --out ./site
+```
+
+`bin/cli.js` is the `npx` entry point: it serves the production build with `vite preview` if one exists (`npm run build` first), otherwise falls back to `vite dev`. With `--stdio` it skips Vite entirely and runs `dist/mcp/stdio.js` in-process, which `npm run build` produces from `vite.mcp.config.ts` (so `--stdio` needs a build — there's no dev-server fallback for it). `bin/cli-bun.js` is a separate entry point used to build the standalone Bun executables (see above); it serves the built SSR handler directly with `Bun.serve` instead of shelling out to Vite. Build one locally with:
 
 ```bash
 npm run build

package/bin/args.js

@@ -1,35 +1,94 @@
 import { resolve } from 'node:path'
 
+export const COMMANDS = ['serve', 'static']
+
+const DEFAULT_OUT_DIR = 'pulumi-package-docs-site'
+
 export function parseArgs(argv) {
-  const options = { dir: process.cwd(), port: '3000', host: false, open: false }
+  const options = {
+    command: 'serve',
+    dir: process.cwd(),
+    port: '3000',
+    host: false,
+    open: false,
+    stdio: false,
+    out: null,
+    base: '/',
+    force: false,
+  }
+  let commandSeen = false
+
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
     if (arg === '--dir' || arg === '-d') {
       options.dir = resolve(argv[++i])
     } else if (arg === '--port' || arg === '-p') {
       options.port = argv[++i]
+    } else if (arg === '--stdio') {
+      options.stdio = true
+    } else if (arg === '--out' || arg === '-o') {
+      options.out = resolve(argv[++i])
+    } else if (arg === '--base' || arg === '-b') {
+      options.base = argv[++i]
+    } else if (arg === '--force' || arg === '-f') {
+      options.force = true
     } else if (arg === '--host') {
       options.host = true
     } else if (arg === '--open') {
       options.open = true
     } else if (arg === '--help' || arg === '-h') {
       options.help = true
+    } else if (!commandSeen && !arg.startsWith('-')) {
+      commandSeen = true
+      if (!COMMANDS.includes(arg)) {
+        options.unknownCommand = arg
+      } else {
+        options.command = arg
+      }
     }
   }
+
+  // Deliberately resolved after the loop: the default depends on --dir, which
+  // may be given after the command.
+  if (options.out === null) options.out = resolve(options.dir, DEFAULT_OUT_DIR)
+
   return options
 }
 
+/**
+ * The address the standalone binary's `Bun.serve` listens on. Bun treats a
+ * missing hostname as every interface, so loopback has to be explicit.
+ */
+export function serveHostname(options) {
+  return options.host ? '0.0.0.0' : '127.0.0.1'
+}
+
 export function printHelp() {
-  console.log(`pulumi-package-docs [options]
+  console.log(`pulumi-package-docs [command] [options]
 
 Serves local documentation for the parameterized/local Pulumi providers used
 by a Pulumi project.
 
+Commands:
+  serve              Serve the docs (default)
+  static             Generate a static site to publish (GitHub/GitLab Pages)
+
 Options:
   -d, --dir <path>   Pulumi project directory to inspect (default: current directory)
+  -h, --help         Show this help message
+
+serve options:
   -p, --port <port>  Port to serve on (default: 3000)
   --host             Expose the server on your network
   --open             Open the docs in your default browser once ready
-  -h, --help         Show this help message
+  --stdio            Run as an MCP server over stdio instead of serving the docs
+                     site (for MCP clients that spawn a server process). The
+                     same tools are served over HTTP at /mcp when serving the site.
+
+static options:
+  -o, --out <path>   Directory to write the site to (default: <dir>/${DEFAULT_OUT_DIR})
+  -b, --base <path>  Base URL path the site is served from, e.g. /my-repo/ for a
+                     GitHub/GitLab Pages project site (default: /)
+  -f, --force        Overwrite --out even if it holds files we didn't generate
 `)
 }

package/bin/args.test.js

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { parseArgs, serveHostname } from './args.js'
+
+describe('serveHostname', () => {
+  it('listens on loopback only unless --host is passed', () => {
+    expect(serveHostname(parseArgs([]))).toBe('127.0.0.1')
+  })
+
+  it('listens on every interface with --host', () => {
+    expect(serveHostname(parseArgs(['--host']))).toBe('0.0.0.0')
+  })
+})
+
+describe('parseArgs', () => {
+  it('defaults to serving the current directory', () => {
+    const options = parseArgs([])
+    expect(options.command).toBe('serve')
+    expect(options.dir).toBe(process.cwd())
+    expect(options.port).toBe('3000')
+  })
+
+  it('reads the static command and its options', () => {
+    const options = parseArgs([
+      'static',
+      '--dir',
+      '/tmp/project',
+      '--out',
+      '/tmp/site',
+      '--base',
+      '/my-repo/',
+      '--force',
+    ])
+    expect(options.command).toBe('static')
+    expect(options.dir).toBe(resolve('/tmp/project'))
+    expect(options.out).toBe(resolve('/tmp/site'))
+    expect(options.base).toBe('/my-repo/')
+    expect(options.force).toBe(true)
+  })
+
+  it('defaults the output directory to one inside the project directory', () => {
+    const options = parseArgs(['static', '--dir', '/tmp/project'])
+    expect(options.out).toBe(
+      resolve('/tmp/project', 'pulumi-package-docs-site'),
+    )
+  })
+
+  it('reports an unknown command rather than treating it as a flag value', () => {
+    const options = parseArgs(['publish'])
+    expect(options.unknownCommand).toBe('publish')
+    expect(options.command).toBe('serve')
+  })
+
+  it("doesn't mistake an option value for the command", () => {
+    const options = parseArgs(['--port', '8080', 'static'])
+    expect(options.command).toBe('static')
+    expect(options.port).toBe('8080')
+  })
+})

package/bin/cli-bun.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env bun
 import { spawn } from 'node:child_process'
-import { parseArgs, printHelp } from './args.js'
-import server from '../dist/server/server.js'
-import embeddedAssets from './embedded-assets.generated.js'
+import { parseArgs, printHelp, serveHostname } from './args.js'
 
 const options = parseArgs(process.argv.slice(2))
 
@@ -11,8 +9,36 @@ if (options.help) {
   process.exit(0)
 }
 
+if (options.unknownCommand) {
+  console.error(`Unknown command: ${options.unknownCommand}\n`)
+  printHelp()
+  process.exit(1)
+}
+
+if (options.command === 'static') {
+  // Generating a site runs a Vite build, which isn't part of this standalone
+  // executable (it only carries the prebuilt server and its assets).
+  console.error(
+    'The standalone binary cannot generate a static site: it has no build toolchain.\n' +
+      'Run `npx pulumi-package-docs static` instead.',
+  )
+  process.exit(1)
+}
+
 process.env.PULUMI_LOCAL_DOCS_DIR = options.dir
 
+if (options.stdio) {
+  // stdout is the MCP protocol channel here, so the banner goes to stderr and the
+  // docs site (and its embedded client assets) is never loaded — these imports stay
+  // dynamic so that stays true, and so `bun build --compile` still bundles both paths.
+  const { runStdioMcpServer } =
+    await import('../src/lib/pulumi/stdio.server.ts')
+  console.error(`Serving provider docs over stdio for: ${options.dir}`)
+  await runStdioMcpServer()
+} else {
+  await serveDocsSite()
+}
+
 function openBrowser(url) {
   const command =
     process.platform === 'darwin'
@@ -30,23 +56,29 @@ function openBrowser(url) {
   child.unref()
 }
 
-console.log(`Serving provider docs for: ${options.dir}`)
-
-const bunServer = Bun.serve({
-  port: Number(options.port),
-  hostname: options.host ? '0.0.0.0' : undefined,
-  async fetch(request) {
-    const url = new URL(request.url)
-    const embeddedPath = embeddedAssets[url.pathname]
-    if (embeddedPath) {
-      return new Response(Bun.file(embeddedPath))
-    }
-    return server.fetch(request)
-  },
-})
-
-const localUrl = `http://localhost:${bunServer.port}/`
-console.log(`  ➜  Local:   ${localUrl}`)
-console.log(`  ➜  MCP:     ${new URL('mcp', localUrl)}`)
-
-if (options.open) openBrowser(localUrl)
+async function serveDocsSite() {
+  const { default: server } = await import('../dist/server/server.js')
+  const { default: embeddedAssets } =
+    await import('./embedded-assets.generated.js')
+
+  console.log(`Serving provider docs for: ${options.dir}`)
+
+  const bunServer = Bun.serve({
+    port: Number(options.port),
+    hostname: serveHostname(options),
+    async fetch(request) {
+      const url = new URL(request.url)
+      const embeddedPath = embeddedAssets[url.pathname]
+      if (embeddedPath) {
+        return new Response(Bun.file(embeddedPath))
+      }
+      return server.fetch(request)
+    },
+  })
+
+  const localUrl = `http://localhost:${bunServer.port}/`
+  console.log(`  ➜  Local:   ${localUrl}`)
+  console.log(`  ➜  MCP:     ${new URL('mcp', localUrl)}`)
+
+  if (options.open) openBrowser(localUrl)
+}

package/bin/cli.js

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawn } from 'node:child_process'
 import { parseArgs, printHelp } from './args.js'
+import { buildStaticSite } from './static.js'
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const require = createRequire(import.meta.url)
@@ -16,35 +17,80 @@ if (options.help) {
   process.exit(0)
 }
 
-const vitePkgJson = require.resolve('vite/package.json')
-const viteBin = join(dirname(vitePkgJson), 'bin', 'vite.js')
-
-const hasProductionBuild = existsSync(
-  join(packageRoot, 'dist', 'server', 'server.js'),
-)
-const viteArgs = [
-  hasProductionBuild ? 'preview' : 'dev',
-  '--port',
-  options.port,
-]
-if (options.host) viteArgs.push('--host')
-if (options.open) viteArgs.push('--open')
-
-if (!hasProductionBuild) {
-  console.log(
-    'No production build found, starting the dev server instead (this is slower).',
-  )
+if (options.unknownCommand) {
+  console.error(`Unknown command: ${options.unknownCommand}\n`)
+  printHelp()
+  process.exit(1)
 }
-console.log(`Serving provider docs for: ${options.dir}`)
 
-const child = spawn(process.execPath, [viteBin, ...viteArgs], {
-  cwd: packageRoot,
-  stdio: 'inherit',
-  env: { ...process.env, PULUMI_LOCAL_DOCS_DIR: options.dir },
-})
+process.env.PULUMI_LOCAL_DOCS_DIR = options.dir
 
-child.on('exit', (code) => process.exit(code ?? 0))
-child.on('error', (err) => {
-  console.error('Failed to start pulumi-package-docs:', err)
+if (options.command === 'static' && options.stdio) {
+  console.error('`--stdio` is a serve option; it has no effect on `static`.')
   process.exit(1)
-})
+}
+
+if (options.stdio) {
+  // stdout is the MCP protocol channel here, so the usual startup banner goes to
+  // stderr and the server runs in-process (no vite, no HTTP server).
+  const stdioEntry = join(packageRoot, 'dist', 'mcp', 'stdio.js')
+  if (!existsSync(stdioEntry)) {
+    console.error(
+      'No production build found. Run `npm run build` before using --stdio.',
+    )
+    process.exit(1)
+  }
+  console.error(`Serving provider docs over stdio for: ${options.dir}`)
+  const { runStdioMcpServer } = await import(stdioEntry)
+  await runStdioMcpServer()
+} else {
+  const vitePkgJson = require.resolve('vite/package.json')
+  const viteBin = join(dirname(vitePkgJson), 'bin', 'vite.js')
+
+  if (options.command === 'static') {
+    try {
+      await buildStaticSite({
+        packageRoot,
+        viteBin,
+        dir: options.dir,
+        out: options.out,
+        base: options.base,
+        force: options.force,
+      })
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : err)
+      process.exit(1)
+    }
+    process.exit(0)
+  }
+
+  const hasProductionBuild = existsSync(
+    join(packageRoot, 'dist', 'server', 'server.js'),
+  )
+  const viteArgs = [
+    hasProductionBuild ? 'preview' : 'dev',
+    '--port',
+    options.port,
+  ]
+  if (options.host) viteArgs.push('--host')
+  if (options.open) viteArgs.push('--open')
+
+  if (!hasProductionBuild) {
+    console.log(
+      'No production build found, starting the dev server instead (this is slower).',
+    )
+  }
+  console.log(`Serving provider docs for: ${options.dir}`)
+
+  const child = spawn(process.execPath, [viteBin, ...viteArgs], {
+    cwd: packageRoot,
+    stdio: 'inherit',
+    env: { ...process.env, PULUMI_LOCAL_DOCS_DIR: options.dir },
+  })
+
+  child.on('exit', (code) => process.exit(code ?? 0))
+  child.on('error', (err) => {
+    console.error('Failed to start pulumi-package-docs:', err)
+    process.exit(1)
+  })
+}

package/bin/cli.test.js

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const cliPath = join(dirname(fileURLToPath(import.meta.url)), 'cli.js')
+
+describe('cli.js', () => {
+  it('rejects `static --stdio` instead of silently serving MCP over stdio', () => {
+    const result = spawnSync(process.execPath, [cliPath, 'static', '--stdio'], {
+      encoding: 'utf8',
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('--stdio')
+    expect(result.stderr).toContain('static')
+  })
+})