pulumi-package-docs 0.1.0

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

@@ -0,0 +1,78 @@
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+import type {
+  LocalPackageRef,
+  ProviderEntry,
+  PulumiSchema,
+} from '@/lib/pulumi/types'
+
+const execFileAsync = promisify(execFile)
+
+const CLI_TIMEOUT_MS = 60_000
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024
+
+function cacheFilePath(projectRoot: string, ref: LocalPackageRef): string {
+  const projectHash = createHash('sha256')
+    .update(projectRoot)
+    .digest('hex')
+    .slice(0, 16)
+  const dir = join(tmpdir(), 'pulumi-package-docs', projectHash)
+  mkdirSync(dir, { recursive: true })
+  return join(dir, `${ref.name}.json`)
+}
+
+function readCache(path: string): PulumiSchema | null {
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as PulumiSchema
+  } catch {
+    return null
+  }
+}
+
+async function fetchViaCli(
+  projectRoot: string,
+  ref: LocalPackageRef,
+): Promise<PulumiSchema> {
+  const args = ['package', 'get-schema', ref.source, ...(ref.parameters ?? [])]
+  const { stdout } = await execFileAsync('pulumi', args, {
+    cwd: projectRoot,
+    timeout: CLI_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER_BYTES,
+  })
+  return JSON.parse(stdout) as PulumiSchema
+}
+
+/**
+ * Resolves the schema for a local package: try the `pulumi` CLI first (it's the
+ * source of truth and works for parameterized providers), and fall back to the
+ * last schema we successfully cached for this project if the CLI call fails.
+ */
+export async function resolveProviderSchema(
+  projectRoot: string,
+  ref: LocalPackageRef,
+): Promise<ProviderEntry> {
+  const cachePath = cacheFilePath(projectRoot, ref)
+
+  try {
+    const schema = await fetchViaCli(projectRoot, ref)
+    writeFileSync(cachePath, JSON.stringify(schema))
+    return { ref, schema, origin: 'cli' }
+  } catch (cliError) {
+    const cached = readCache(cachePath)
+    if (cached) {
+      return { ref, schema: cached, origin: 'cache' }
+    }
+    return {
+      ref,
+      schema: null,
+      origin: 'error',
+      error: cliError instanceof Error ? cliError.message : String(cliError),
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+
+import { tokenDisplayName } from '@/lib/pulumi/token'
+
+describe('tokenDisplayName', () => {
+  it('returns the segment after the last colon for a resource token', () => {
+    expect(tokenDisplayName('random:index/randomString:RandomString')).toBe(
+      'RandomString',
+    )
+  })
+
+  it('returns the segment after the last colon for a function token', () => {
+    expect(
+      tokenDisplayName('random:index/randomInteger:getRandomInteger'),
+    ).toBe('getRandomInteger')
+  })
+
+  it('returns the token unchanged when it has no colon', () => {
+    expect(tokenDisplayName('plainName')).toBe('plainName')
+  })
+})

package/src/lib/pulumi/token.ts

@@ -0,0 +1,10 @@
+/**
+ * Schema tokens look like `random:index/randomString:RandomString` (resources)
+ * or `random:index/randomInteger:randomInteger` (functions). The segment after
+ * the last colon is the name every generated SDK exports for that member, and
+ * is unique within the provider, so it makes a readable display name.
+ */
+export function tokenDisplayName(token: string): string {
+  const short = token.split(':').pop()
+  return short && short.length > 0 ? short : token
+}

package/src/lib/pulumi/types.ts

@@ -0,0 +1,62 @@
+/** A locally-added package entry from a project's Pulumi.yaml `packages` section. */
+export interface LocalPackageRef {
+  /** The local alias the project uses for this package, e.g. "random". */
+  name: string
+  /** The base provider/plugin this package resolves through, e.g. "terraform-provider". */
+  source: string
+  version?: string
+  /** Parameterization arguments, e.g. ["hashicorp/random"] for a bridged Terraform provider. */
+  parameters?: string[]
+}
+
+export interface PulumiProject {
+  root: string
+  name?: string
+  runtime?: string
+  packages: LocalPackageRef[]
+}
+
+export interface SchemaProperty {
+  type?: string
+  $ref?: string
+  description?: string
+  items?: SchemaProperty
+}
+
+export interface SchemaResource {
+  description?: string
+  properties?: Record<string, SchemaProperty>
+  required?: string[]
+  inputProperties?: Record<string, SchemaProperty>
+  requiredInputs?: string[]
+  deprecationMessage?: string
+}
+
+export interface SchemaFunction {
+  description?: string
+  inputs?: {
+    properties?: Record<string, SchemaProperty>
+    required?: string[]
+  }
+  outputs?: {
+    properties?: Record<string, SchemaProperty>
+    required?: string[]
+  }
+}
+
+export interface PulumiSchema {
+  name: string
+  version?: string
+  description?: string
+  resources?: Record<string, SchemaResource>
+  functions?: Record<string, SchemaFunction>
+}
+
+export type SchemaOrigin = 'cli' | 'cache'
+
+export interface ProviderEntry {
+  ref: LocalPackageRef
+  schema: PulumiSchema | null
+  origin: SchemaOrigin | 'error'
+  error?: string
+}

package/src/routeTree.gen.ts

@@ -0,0 +1,187 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as McpRouteImport } from './routes/mcp'
+import { Route as ProvidersNameRouteImport } from './routes/providers.$name'
+import { Route as ProvidersNameIndexRouteImport } from './routes/providers.$name.index'
+import { Route as ProvidersNameFunctionsTokenRouteImport } from './routes/providers.$name.functions.$token'
+import { Route as ProvidersNameResourcesTokenRouteImport } from './routes/providers.$name.resources.$token'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const McpRoute = McpRouteImport.update({
+  id: '/mcp',
+  path: '/mcp',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ProvidersNameRoute = ProvidersNameRouteImport.update({
+  id: '/providers/$name',
+  path: '/providers/$name',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ProvidersNameIndexRoute = ProvidersNameIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => ProvidersNameRoute,
+} as any)
+const ProvidersNameFunctionsTokenRoute =
+  ProvidersNameFunctionsTokenRouteImport.update({
+    id: '/functions/$token',
+    path: '/functions/$token',
+    getParentRoute: () => ProvidersNameRoute,
+  } as any)
+const ProvidersNameResourcesTokenRoute =
+  ProvidersNameResourcesTokenRouteImport.update({
+    id: '/resources/$token',
+    path: '/resources/$token',
+    getParentRoute: () => ProvidersNameRoute,
+  } as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/mcp': typeof McpRoute
+  '/providers/$name': typeof ProvidersNameRouteWithChildren
+  '/providers/$name/': typeof ProvidersNameIndexRoute
+  '/providers/$name/functions/$token': typeof ProvidersNameFunctionsTokenRoute
+  '/providers/$name/resources/$token': typeof ProvidersNameResourcesTokenRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/mcp': typeof McpRoute
+  '/providers/$name': typeof ProvidersNameIndexRoute
+  '/providers/$name/functions/$token': typeof ProvidersNameFunctionsTokenRoute
+  '/providers/$name/resources/$token': typeof ProvidersNameResourcesTokenRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/mcp': typeof McpRoute
+  '/providers/$name': typeof ProvidersNameRouteWithChildren
+  '/providers/$name/': typeof ProvidersNameIndexRoute
+  '/providers/$name/functions/$token': typeof ProvidersNameFunctionsTokenRoute
+  '/providers/$name/resources/$token': typeof ProvidersNameResourcesTokenRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/mcp'
+    | '/providers/$name'
+    | '/providers/$name/'
+    | '/providers/$name/functions/$token'
+    | '/providers/$name/resources/$token'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/mcp'
+    | '/providers/$name'
+    | '/providers/$name/functions/$token'
+    | '/providers/$name/resources/$token'
+  id:
+    | '__root__'
+    | '/'
+    | '/mcp'
+    | '/providers/$name'
+    | '/providers/$name/'
+    | '/providers/$name/functions/$token'
+    | '/providers/$name/resources/$token'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  McpRoute: typeof McpRoute
+  ProvidersNameRoute: typeof ProvidersNameRouteWithChildren
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/mcp': {
+      id: '/mcp'
+      path: '/mcp'
+      fullPath: '/mcp'
+      preLoaderRoute: typeof McpRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/providers/$name': {
+      id: '/providers/$name'
+      path: '/providers/$name'
+      fullPath: '/providers/$name'
+      preLoaderRoute: typeof ProvidersNameRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/providers/$name/': {
+      id: '/providers/$name/'
+      path: '/'
+      fullPath: '/providers/$name/'
+      preLoaderRoute: typeof ProvidersNameIndexRouteImport
+      parentRoute: typeof ProvidersNameRoute
+    }
+    '/providers/$name/functions/$token': {
+      id: '/providers/$name/functions/$token'
+      path: '/functions/$token'
+      fullPath: '/providers/$name/functions/$token'
+      preLoaderRoute: typeof ProvidersNameFunctionsTokenRouteImport
+      parentRoute: typeof ProvidersNameRoute
+    }
+    '/providers/$name/resources/$token': {
+      id: '/providers/$name/resources/$token'
+      path: '/resources/$token'
+      fullPath: '/providers/$name/resources/$token'
+      preLoaderRoute: typeof ProvidersNameResourcesTokenRouteImport
+      parentRoute: typeof ProvidersNameRoute
+    }
+  }
+}
+
+interface ProvidersNameRouteChildren {
+  ProvidersNameIndexRoute: typeof ProvidersNameIndexRoute
+  ProvidersNameFunctionsTokenRoute: typeof ProvidersNameFunctionsTokenRoute
+  ProvidersNameResourcesTokenRoute: typeof ProvidersNameResourcesTokenRoute
+}
+
+const ProvidersNameRouteChildren: ProvidersNameRouteChildren = {
+  ProvidersNameIndexRoute: ProvidersNameIndexRoute,
+  ProvidersNameFunctionsTokenRoute: ProvidersNameFunctionsTokenRoute,
+  ProvidersNameResourcesTokenRoute: ProvidersNameResourcesTokenRoute,
+}
+
+const ProvidersNameRouteWithChildren = ProvidersNameRoute._addFileChildren(
+  ProvidersNameRouteChildren,
+)
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  McpRoute: McpRoute,
+  ProvidersNameRoute: ProvidersNameRouteWithChildren,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

package/src/router.tsx

@@ -0,0 +1,19 @@
+import { createRouter as createTanStackRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+    defaultPreloadStaleTime: 0,
+  })
+
+  return router
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}

package/src/routes/__root.tsx

@@ -0,0 +1,59 @@
+import {
+  HeadContent,
+  Link,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router'
+
+import { PulumiLogo } from '@/components/PulumiLogo'
+import appCss from '../styles.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'Local Provider Docs',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+      {
+        rel: 'icon',
+        href: 'https://brand.pulumi.com/media/images/logos/icon-rounded-64w.png',
+      },
+    ],
+  }),
+  shellComponent: RootDocument,
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <header className="site-header">
+          <Link to="/" className="site-brand">
+            <PulumiLogo height={22} />
+            <span className="site-brand-divider" aria-hidden="true" />
+            <span className="site-brand-name">Local Provider Docs</span>
+          </Link>
+        </header>
+        {children}
+
+        <Scripts />
+      </body>
+    </html>
+  )
+}

package/src/routes/index.tsx

@@ -0,0 +1,78 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+
+import { listProviders } from '@/lib/pulumi/api'
+
+export const Route = createFileRoute('/')({
+  loader: () => listProviders(),
+  component: Home,
+})
+
+function Home() {
+  const { targetDir, project, providers } = Route.useLoaderData()
+
+  if (!project) {
+    return (
+      <main>
+        <h1>Local Provider Docs</h1>
+        <p className="empty-state">
+          No Pulumi project was found at <code>{targetDir}</code> (or any parent
+          directory). Run this from inside a Pulumi project directory, or with{' '}
+          <code>--dir &lt;path&gt;</code> pointing at one.
+        </p>
+      </main>
+    )
+  }
+
+  return (
+    <main>
+      <h1>Local Provider Docs</h1>
+      <p className="subtitle">
+        {project.name ?? 'Pulumi project'} &middot; <code>{project.root}</code>
+      </p>
+
+      {providers.length === 0 ? (
+        <p className="empty-state">
+          This project's <code>Pulumi.yaml</code> has no <code>packages</code>{' '}
+          section, so there are no local or parameterized providers to show docs
+          for yet. Add one with <code>pulumi package add</code>.
+        </p>
+      ) : (
+        <ul className="provider-list">
+          {providers.map((provider) => (
+            <li key={provider.name} className="provider-card">
+              <Link to="/providers/$name" params={{ name: provider.name }}>
+                <span className="provider-name">{provider.name}</span>
+                <span className="provider-source">
+                  {provider.source}
+                  {provider.version ? ` @ ${provider.version}` : ''}
+                  {provider.parameters?.length
+                    ? ` (${provider.parameters.join(' ')})`
+                    : ''}
+                </span>
+              </Link>
+              {provider.origin === 'error' ? (
+                <p className="banner banner-failure">
+                  Failed to load schema: {provider.error}
+                </p>
+              ) : (
+                <p className="provider-stats">
+                  {provider.resourceCount} resource
+                  {provider.resourceCount === 1 ? '' : 's'}
+                  {' · '}
+                  {provider.functionCount} function
+                  {provider.functionCount === 1 ? '' : 's'}
+                  {provider.origin === 'cache' && (
+                    <>
+                      {' · '}
+                      <span className="badge badge-info">from cache</span>
+                    </>
+                  )}
+                </p>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  )
+}

package/src/routes/mcp.ts

@@ -0,0 +1,30 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+
+import { createMcpServer } from '@/lib/pulumi/mcp.server'
+
+/**
+ * Stateless MCP endpoint: a fresh server + transport per request, so concurrent
+ * requests never share state. There's nothing here worth persisting across
+ * requests (schemas are re-resolved, cached on disk, each call) and every tool
+ * is a plain read, so statelessness keeps this simple.
+ */
+async function handleMcpRequest({ request }: { request: Request }) {
+  const server = createMcpServer()
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  })
+  await server.connect(transport)
+  return transport.handleRequest(request)
+}
+
+export const Route = createFileRoute('/mcp')({
+  server: {
+    handlers: {
+      GET: handleMcpRequest,
+      POST: handleMcpRequest,
+      DELETE: handleMcpRequest,
+    },
+  },
+})

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

@@ -0,0 +1,47 @@
+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'
+
+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()
+    return {
+      providerName: params.name,
+      token: params.token,
+      fn,
+      runtime: entry?.runtime,
+    }
+  },
+  component: FunctionDetail,
+  notFoundComponent: () => (
+    <main>
+      <p>
+        No function with that name was found.{' '}
+        <Link to="/">Back to all providers.</Link>
+      </p>
+    </main>
+  ),
+})
+
+function FunctionDetail() {
+  const { providerName, token, fn, runtime } = Route.useLoaderData()
+
+  return (
+    <MemberDetail
+      providerName={providerName}
+      kind="Function"
+      displayName={tokenDisplayName(token)}
+      token={token}
+      description={fn.description}
+      runtime={runtime}
+      inputProperties={fn.inputs?.properties}
+      requiredInputs={fn.inputs?.required}
+      outputProperties={fn.outputs?.properties}
+      requiredOutputs={fn.outputs?.required}
+    />
+  )
+}