pulumi-package-docs 0.7.0 → 0.9.0

package/src/lib/pulumi/mcp.server.test.ts

@@ -0,0 +1,112 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { createMcpServer } from '@/lib/pulumi/mcp.server'
+
+let projectDir: string
+const originalEnv = process.env.PULUMI_LOCAL_DOCS_DIR
+
+beforeEach(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'pulumi-package-docs-mcp-test-'))
+  writeFileSync(
+    join(projectDir, 'Pulumi.yaml'),
+    `name: my-project\nruntime: nodejs\n`,
+  )
+  process.env.PULUMI_LOCAL_DOCS_DIR = projectDir
+})
+
+afterEach(() => {
+  rmSync(projectDir, { recursive: true, force: true })
+  if (originalEnv === undefined) delete process.env.PULUMI_LOCAL_DOCS_DIR
+  else process.env.PULUMI_LOCAL_DOCS_DIR = originalEnv
+})
+
+/**
+ * Drives the MCP server the same way the stdio entry point does — a plain in-process
+ * server with a transport attached, no HTTP server and no TanStack Start runtime.
+ */
+async function connectClient(): Promise<Client> {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  const client = new Client({ name: 'test-client', version: '0.0.0' })
+  await Promise.all([
+    createMcpServer().connect(serverTransport),
+    client.connect(clientTransport),
+  ])
+  return client
+}
+
+function parseTextResult(result: unknown): unknown {
+  const { content } = result as {
+    content?: Array<{ type: string; text: string }>
+  }
+  expect(content?.[0]?.type).toBe('text')
+  return JSON.parse(content![0]!.text)
+}
+
+describe('createMcpServer', () => {
+  it('advertises the provider docs tools', async () => {
+    const client = await connectClient()
+
+    const { tools } = await client.listTools()
+
+    expect(tools.map((tool) => tool.name).sort()).toEqual([
+      'get_function',
+      'get_resource',
+      'list_functions',
+      'list_providers',
+      'list_resources',
+      'search_members',
+    ])
+    await client.close()
+  })
+
+  it('reports the discovered project from list_providers', async () => {
+    const client = await connectClient()
+
+    const result = await client.callTool({ name: 'list_providers' })
+
+    expect(parseTextResult(result)).toMatchObject({
+      targetDir: projectDir,
+      project: { root: projectDir, name: 'my-project', runtime: 'nodejs' },
+      providers: [],
+    })
+    await client.close()
+  })
+
+  it('returns no matches from search_members when the project has no packages', async () => {
+    const client = await connectClient()
+
+    const result = await client.callTool({
+      name: 'search_members',
+      arguments: { query: 'bucket' },
+    })
+
+    expect(parseTextResult(result)).toEqual({
+      query: 'bucket',
+      matchCount: 0,
+      matches: [],
+    })
+    await client.close()
+  })
+
+  it('surfaces a tool error for a provider that is not declared in Pulumi.yaml', async () => {
+    const client = await connectClient()
+
+    const result = await client.callTool({
+      name: 'list_resources',
+      arguments: { provider: 'nope' },
+    })
+
+    expect(result.isError).toBe(true)
+    expect(JSON.stringify(result.content)).toContain(
+      'No local provider named \\"nope\\"',
+    )
+    await client.close()
+  })
+})

package/src/lib/pulumi/mcp.server.ts

@@ -2,8 +2,6 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import { z } from 'zod'
 
-import { getProvider, listProviders } from '@/lib/pulumi/api'
-import type { ProviderDetail } from '@/lib/pulumi/api'
 import { resolveDescription } from '@/lib/pulumi/description'
 import { getTargetDir, loadPulumiProject } from '@/lib/pulumi/discovery.server'
 import {
@@ -14,6 +12,11 @@ import {
 } from '@/lib/pulumi/examples'
 import { formatType } from '@/lib/pulumi/format'
 import { formatPropertyName } from '@/lib/pulumi/naming'
+import {
+  loadProjectSummary,
+  loadProviderDetail,
+} from '@/lib/pulumi/providers.server'
+import type { ProviderDetail } from '@/lib/pulumi/providers.server'
 import { resolveProviderSchema } from '@/lib/pulumi/schema.server'
 import { tokenDisplayName } from '@/lib/pulumi/token'
 import type {
@@ -30,7 +33,7 @@ function textResult(data: unknown): CallToolResult {
 async function requireProvider(
   providerName: string,
 ): Promise<ProviderDetail & { schema: NonNullable<ProviderDetail['schema']> }> {
-  const detail = await getProvider({ data: providerName })
+  const detail = await loadProviderDetail(providerName)
   if (!detail) {
     throw new Error(
       `No local provider named "${providerName}" was found. Call list_providers to see the providers declared in this project's Pulumi.yaml.`,
@@ -100,8 +103,10 @@ function memberDetail(
 }
 
 /**
- * Builds a fresh MCP server with the local-provider-docs tools registered. Called once
- * per HTTP request (see `src/routes/mcp.ts`) so concurrent requests never share state.
+ * Builds a fresh MCP server with the local-provider-docs tools registered. Transport
+ * agnostic: `src/routes/mcp.ts` calls it once per HTTP request (so concurrent requests
+ * never share state), and `src/lib/pulumi/stdio.server.ts` calls it once for the
+ * lifetime of a stdio process.
  */
 export function createMcpServer(): McpServer {
   const server = new McpServer({
@@ -116,7 +121,7 @@ export function createMcpServer(): McpServer {
       description:
         "List the local/parameterized Pulumi providers declared in this project's Pulumi.yaml (added with `pulumi package add`), with their source, version, and resource/function counts.",
     },
-    async () => textResult(await listProviders()),
+    async () => textResult(await loadProjectSummary()),
   )
 
   server.registerTool(

package/src/lib/pulumi/providers.server.ts

@@ -0,0 +1,80 @@
+import { getTargetDir, loadPulumiProject } from '@/lib/pulumi/discovery.server'
+import { resolveProviderSchema } from '@/lib/pulumi/schema.server'
+import type { ProviderEntry, PulumiProject } from '@/lib/pulumi/types'
+
+export interface ProviderSummary {
+  name: string
+  source: string
+  version?: string
+  parameters?: string[]
+  resourceCount: number
+  functionCount: number
+  origin: ProviderEntry['origin']
+  error?: string
+}
+
+export interface ProjectSummary {
+  targetDir: string
+  project: Pick<PulumiProject, 'root' | 'name' | 'runtime'> | null
+  providers: ProviderSummary[]
+}
+
+export interface ProviderDetail extends ProviderEntry {
+  /** The Pulumi project's runtime (e.g. "nodejs", "python", "go"), used to render Inputs/Outputs names in that language's casing. */
+  runtime?: string
+}
+
+/**
+ * The project + provider summaries shown on the index route and by the MCP
+ * `list_providers` tool. Plain async functions (no TanStack Start server-fn
+ * wrapper) so they can run either inside the web server or in the stdio MCP
+ * process, which has no HTTP server at all.
+ */
+export async function loadProjectSummary(): Promise<ProjectSummary> {
+  const targetDir = getTargetDir()
+  const project = loadPulumiProject(targetDir)
+
+  if (!project) {
+    return { targetDir, project: null, providers: [] }
+  }
+
+  const entries = await Promise.all(
+    project.packages.map((ref) => resolveProviderSchema(project.root, ref)),
+  )
+
+  const providers: ProviderSummary[] = entries.map((entry) => ({
+    name: entry.ref.name,
+    source: entry.ref.source,
+    version: entry.ref.version,
+    parameters: entry.ref.parameters,
+    resourceCount: Object.keys(entry.schema?.resources ?? {}).length,
+    functionCount: Object.keys(entry.schema?.functions ?? {}).length,
+    origin: entry.origin,
+    error: entry.error,
+  }))
+
+  return {
+    targetDir,
+    project: {
+      root: project.root,
+      name: project.name,
+      runtime: project.runtime,
+    },
+    providers,
+  }
+}
+
+/** The fully resolved schema for one local provider, or null if the project or provider isn't found. */
+export async function loadProviderDetail(
+  name: string,
+): Promise<ProviderDetail | null> {
+  const targetDir = getTargetDir()
+  const project = loadPulumiProject(targetDir)
+  if (!project) return null
+
+  const ref = project.packages.find((p) => p.name === name)
+  if (!ref) return null
+
+  const entry = await resolveProviderSchema(project.root, ref)
+  return { ...entry, runtime: project.runtime }
+}

package/src/lib/pulumi/stdio.server.ts

@@ -0,0 +1,16 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+import { createMcpServer } from '@/lib/pulumi/mcp.server'
+
+/**
+ * Serves the same provider-docs tools as the `/mcp` HTTP route over stdio, for MCP
+ * clients that spawn a server process instead of connecting to a URL.
+ *
+ * Unlike the HTTP route this is a single long-lived server (one process, one client),
+ * and stdout is the protocol channel — nothing on this path may write to it, so any
+ * diagnostics belong on stderr.
+ */
+export async function runStdioMcpServer(): Promise<void> {
+  const server = createMcpServer()
+  await server.connect(new StdioServerTransport())
+}

package/src/lib/pulumi/token.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 
-import { tokenDisplayName } from '@/lib/pulumi/token'
+import {
+  findTokenBySlug,
+  tokenDisplayName,
+  tokenSlug,
+} from '@/lib/pulumi/token'
 
 describe('tokenDisplayName', () => {
   it('returns the segment after the last colon for a resource token', () => {
@@ -19,3 +23,42 @@ describe('tokenDisplayName', () => {
     expect(tokenDisplayName('plainName')).toBe('plainName')
   })
 })
+
+describe('tokenSlug', () => {
+  it('replaces the token separators with dashes', () => {
+    expect(tokenSlug('random:index/randomString:RandomString')).toBe(
+      'random-index-randomString-RandomString',
+    )
+  })
+
+  it('leaves an already-safe token unchanged', () => {
+    expect(tokenSlug('plainName')).toBe('plainName')
+  })
+
+  it('collapses a run of unsafe characters into a single dash', () => {
+    expect(tokenSlug('aws:s3//bucket:Bucket')).toBe('aws-s3-bucket-Bucket')
+  })
+})
+
+describe('findTokenBySlug', () => {
+  const tokens = [
+    'random:index/randomString:RandomString',
+    'random:index/randomPet:RandomPet',
+  ]
+
+  it('finds the token a slug was made from', () => {
+    expect(findTokenBySlug(tokens, 'random-index-randomPet-RandomPet')).toBe(
+      'random:index/randomPet:RandomPet',
+    )
+  })
+
+  it('also accepts the raw token', () => {
+    expect(
+      findTokenBySlug(tokens, 'random:index/randomString:RandomString'),
+    ).toBe('random:index/randomString:RandomString')
+  })
+
+  it('returns undefined when nothing matches', () => {
+    expect(findTokenBySlug(tokens, 'nope')).toBeUndefined()
+  })
+})

package/src/lib/pulumi/token.ts

@@ -8,3 +8,31 @@ export function tokenDisplayName(token: string): string {
   const short = token.split(':').pop()
   return short && short.length > 0 ? short : token
 }
+
+/**
+ * A URL- and filesystem-safe form of a token, used as the `$token` route param.
+ *
+ * Tokens contain `:` and `/`, which only survive a URL as percent-escapes —
+ * and static hosts (GitHub/GitLab Pages) decode those before matching a file,
+ * so `random%3Aindex%2FrandomString%3ARandomString` would never resolve to the
+ * page generated for it. Replacing the separators keeps one URL shape that
+ * works both when served dynamically and as prerendered files on disk.
+ */
+export function tokenSlug(token: string): string {
+  return token.replace(/[^a-zA-Z0-9._~-]+/g, '-')
+}
+
+/**
+ * Resolves a `$token` route param back to the schema token it names. Accepts
+ * either a slug (what links produce) or the raw token, so a URL pasted from
+ * schema output still works.
+ */
+export function findTokenBySlug(
+  tokens: Iterable<string>,
+  slug: string,
+): string | undefined {
+  for (const token of tokens) {
+    if (token === slug || tokenSlug(token) === slug) return token
+  }
+  return undefined
+}

package/src/lib/static-docs.ts

@@ -0,0 +1,15 @@
+/**
+ * True when the app is being built as a static site (`pulumi-package-docs
+ * static`), for publishing to GitHub/GitLab Pages.
+ *
+ * A static build has no server behind it, so its pages can't call the server
+ * functions in `@/lib/pulumi/api` on the client. Every page is prerendered
+ * with its data already baked in and shipped without the hydration script:
+ * links then behave as ordinary anchors and each page load is self-contained,
+ * which also keeps a large provider's schema out of the pages that don't need
+ * it.
+ *
+ * Vite inlines `import.meta.env.VITE_*` at build time, so this folds away to a
+ * constant in both builds.
+ */
+export const isStaticDocs = import.meta.env.VITE_STATIC_DOCS === 'true'

package/src/router.tsx

@@ -4,6 +4,9 @@ import { routeTree } from './routeTree.gen'
 export function getRouter() {
   const router = createTanStackRouter({
     routeTree,
+    // Set from Vite's `base`, so a static build published under a project
+    // path (e.g. https://<user>.github.io/<repo>/) still links correctly.
+    basepath: import.meta.env.BASE_URL,
     scrollRestoration: true,
     defaultPreload: 'intent',
     defaultPreloadStaleTime: 0,

package/src/routes/__root.tsx

@@ -6,7 +6,8 @@ import {
 } from '@tanstack/react-router'
 
 import { PulumiLogo } from '@/components/PulumiLogo'
-import { ThemeToggle } from '@/components/ThemeToggle'
+import { StaticThemeToggle, ThemeToggle } from '@/components/ThemeToggle'
+import { isStaticDocs } from '@/lib/static-docs'
 import appCss from '../styles.css?url'
 
 // Runs before hydration so an explicit theme choice applies before first
@@ -57,12 +58,14 @@ function RootDocument({ children }: { children: React.ReactNode }) {
               <span className="site-brand-divider" aria-hidden="true" />
               <span className="site-brand-name">Package Docs</span>
             </Link>
-            <ThemeToggle />
+            {isStaticDocs ? <StaticThemeToggle /> : <ThemeToggle />}
           </div>
         </header>
         {children}
 
-        <Scripts />
+        {/* A static build has no server to call back into, so it ships
+            without the hydration script and navigates as plain links. */}
+        {isStaticDocs ? null : <Scripts />}
       </body>
     </html>
   )

package/src/routes/providers.$name.functions.$token.tsx

@@ -2,16 +2,19 @@ import { Link, createFileRoute, notFound } from '@tanstack/react-router'
 
 import { MemberDetail } from '@/components/MemberDetail'
 import { getProvider } from '@/lib/pulumi/api'
-import { tokenDisplayName } from '@/lib/pulumi/token'
+import { findTokenBySlug, tokenDisplayName } from '@/lib/pulumi/token'
 
 export const Route = createFileRoute('/providers/$name/functions/$token')({
   loader: async ({ params }) => {
     const entry = await getProvider({ data: params.name })
-    const fn = entry?.schema?.functions?.[params.token]
-    if (!fn) throw notFound()
+    const functions = entry?.schema?.functions
+    const token =
+      functions && findTokenBySlug(Object.keys(functions), params.token)
+    const fn = token ? functions[token] : undefined
+    if (!token || !fn) throw notFound()
     return {
       providerName: params.name,
-      token: params.token,
+      token,
       fn,
       runtime: entry?.runtime,
     }

package/src/routes/providers.$name.index.tsx

@@ -3,7 +3,7 @@ import { Link, createFileRoute, notFound } from '@tanstack/react-router'
 import { getProvider } from '@/lib/pulumi/api'
 import { resolveDescription } from '@/lib/pulumi/description'
 import { summarizeDescription } from '@/lib/pulumi/examples'
-import { tokenDisplayName } from '@/lib/pulumi/token'
+import { tokenDisplayName, tokenSlug } from '@/lib/pulumi/token'
 import type { SchemaFunction, SchemaResource } from '@/lib/pulumi/types'
 
 export const Route = createFileRoute('/providers/$name/')({
@@ -43,7 +43,7 @@ function MemberListItem({
 
   return (
     <li className="doc-list-item">
-      <Link to={to} params={{ name: providerName, token }}>
+      <Link to={to} params={{ name: providerName, token: tokenSlug(token) }}>
         <code>{tokenDisplayName(token)}</code>
       </Link>
       {deprecated && <span className="badge badge-warning">Deprecated</span>}

package/src/routes/providers.$name.resources.$token.tsx

@@ -2,16 +2,19 @@ import { Link, createFileRoute, notFound } from '@tanstack/react-router'
 
 import { MemberDetail } from '@/components/MemberDetail'
 import { getProvider } from '@/lib/pulumi/api'
-import { tokenDisplayName } from '@/lib/pulumi/token'
+import { findTokenBySlug, tokenDisplayName } from '@/lib/pulumi/token'
 
 export const Route = createFileRoute('/providers/$name/resources/$token')({
   loader: async ({ params }) => {
     const entry = await getProvider({ data: params.name })
-    const resource = entry?.schema?.resources?.[params.token]
-    if (!resource) throw notFound()
+    const resources = entry?.schema?.resources
+    const token =
+      resources && findTokenBySlug(Object.keys(resources), params.token)
+    const resource = token ? resources[token] : undefined
+    if (!token || !resource) throw notFound()
     return {
       providerName: params.name,
-      token: params.token,
+      token,
       resource,
       runtime: entry?.runtime,
     }

package/vite.config.ts

@@ -38,9 +38,49 @@ function printMcpUrl(): Plugin {
   }
 }
 
+// Set by `pulumi-package-docs static` (see bin/static.js). A static build
+// prerenders every page to HTML under `dist-static/client` so the result can
+// be published to GitHub/GitLab Pages, where there's no server to render them.
+const staticDocs = process.env.VITE_STATIC_DOCS === 'true'
+// The path the site is served under, e.g. "/<repo>/" for a GitHub/GitLab
+// Pages project site. Vite prefixes asset URLs with it, and the router picks
+// it up as its basepath via `import.meta.env.BASE_URL`.
+const base = process.env.PULUMI_DOCS_BASE || '/'
+
 const config = defineConfig({
+  base,
+  // A static build goes to its own output directory, so generating a site
+  // never clobbers the `dist/` build that `pulumi-package-docs` serves.
+  ...(staticDocs
+    ? {
+        build: { outDir: 'dist-static' },
+        preview: { host: '127.0.0.1' },
+      }
+    : {}),
   resolve: { tsconfigPaths: true },
-  plugins: [tanstackStart(), viteReact(), printMcpUrl()],
+  plugins: [
+    tanstackStart(
+      staticDocs
+        ? {
+            // Crawling from the index reaches every provider page and, from
+            // there, every resource/function page — so the page list follows
+            // whatever the project's Pulumi.yaml declares, with nothing to
+            // enumerate here.
+            pages: [{ path: '/' }],
+            prerender: {
+              enabled: true,
+              crawlLinks: true,
+              failOnError: true,
+              // `/mcp` is a server endpoint (Streamable HTTP), not a page;
+              // there's nothing to prerender and no server to serve it from.
+              filter: (page) => page.path !== '/mcp',
+            },
+          }
+        : undefined,
+    ),
+    viteReact(),
+    printMcpUrl(),
+  ],
 })
 
 export default config

package/dist/client/assets/MemberDetail-BS9DbqEt.js

@@ -1 +0,0 @@
-import{o as e}from"./useSelector-BIt42tGI.js";import{o as t}from"./index-2FzxAhzN.js";import{i as n,n as r,o as i,r as a}from"./token-oQmZfAP3.js";var o=e();function s({example:e}){return e?(0,o.jsxs)(`div`,{className:`code-example`,children:[(0,o.jsx)(`span`,{className:`code-example-lang`,children:e.language}),(0,o.jsx)(`pre`,{children:(0,o.jsx)(`code`,{children:e.code})})]}):(0,o.jsx)(`p`,{className:`empty-state`,children:`No examples in the schema.`})}function c(e){if(!e)return`any`;if(e.$ref){let t=e.$ref.split(`/`).pop()??e.$ref;return decodeURIComponent(t)}return e.type===`array`&&e.items?`${c(e.items)}[]`:e.type??`any`}function l(e){return e.replace(/([a-z0-9])([A-Z])/g,`$1_$2`).replace(/([A-Z]+)([A-Z][a-z])/g,`$1_$2`).toLowerCase()}function u(e){return e.length===0?e:e.charAt(0).toUpperCase()+e.slice(1)}function d(e,t){switch(t){case`python`:return l(e);case`go`:case`dotnet`:return u(e);default:return e}}function f({properties:e,required:t,runtime:n}){let r=Object.keys(e??{});if(r.length===0)return(0,o.jsx)(`p`,{className:`empty-state`,children:`None`});let a=new Set(t??[]);return(0,o.jsxs)(`table`,{className:`props-table`,children:[(0,o.jsx)(`thead`,{children:(0,o.jsxs)(`tr`,{children:[(0,o.jsx)(`th`,{children:`Name`}),(0,o.jsx)(`th`,{children:`Type`}),(0,o.jsx)(`th`,{children:`Required`}),(0,o.jsx)(`th`,{children:`Description`})]})}),(0,o.jsx)(`tbody`,{children:r.map(t=>{let r=e[t];return(0,o.jsxs)(`tr`,{children:[(0,o.jsx)(`td`,{children:(0,o.jsx)(`code`,{children:d(t,n)})}),(0,o.jsx)(`td`,{children:(0,o.jsx)(`code`,{children:c(r)})}),(0,o.jsx)(`td`,{children:a.has(t)?`yes`:`no`}),(0,o.jsx)(`td`,{children:i(r.description,n)??``})]},t)})})]})}function p({providerName:e,kind:c,displayName:l,token:u,description:d,deprecationMessage:p,runtime:m,inputProperties:h,requiredInputs:g,outputProperties:_,requiredOutputs:v}){let y=i(d,m),b=n(y),x=a(r(y),m);return(0,o.jsxs)(`main`,{className:`provider-detail`,children:[(0,o.jsxs)(t,{to:`/providers/$name`,params:{name:e},className:`back-link`,children:[`← Back to `,e]}),(0,o.jsx)(`h1`,{children:l}),(0,o.jsxs)(`p`,{className:`subtitle`,children:[(0,o.jsx)(`span`,{className:`badge ${c===`Resource`?`badge-resource`:`badge-function`}`,children:c}),` `,`· `,(0,o.jsx)(`code`,{children:u})]}),p&&(0,o.jsxs)(`p`,{className:`banner banner-warning`,children:[`Deprecated: `,p]}),b?.split(/\n{2,}/).map((e,t)=>(0,o.jsx)(`p`,{children:e},t)),(0,o.jsx)(`h2`,{children:`Example`}),(0,o.jsx)(s,{example:x}),(0,o.jsx)(`h2`,{children:`Inputs`}),(0,o.jsx)(f,{properties:h,required:g,runtime:m}),(0,o.jsx)(`h2`,{children:`Outputs`}),(0,o.jsx)(f,{properties:_,required:v,runtime:m})]})}export{p as t};