pulumi-package-docs 0.1.0

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

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { parse } from 'yaml'
+
+import type { LocalPackageRef, PulumiProject } from '@/lib/pulumi/types'
+
+const PROJECT_FILE_NAMES = ['Pulumi.yaml', 'Pulumi.yml']
+
+/**
+ * The directory of the Pulumi program to inspect. `bin/cli.js` sets this to the
+ * directory the user ran `npx pulumi-package-docs` from, since the dev/preview
+ * server itself runs with this package's own directory as its cwd.
+ */
+export function getTargetDir(): string {
+  return process.env.PULUMI_LOCAL_DOCS_DIR || process.cwd()
+}
+
+function findProjectFile(startDir: string): string | null {
+  let dir = startDir
+  for (;;) {
+    for (const fileName of PROJECT_FILE_NAMES) {
+      const candidate = join(dir, fileName)
+      if (existsSync(candidate)) return candidate
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function toLocalPackageRefs(packages: unknown): LocalPackageRef[] {
+  if (!packages || typeof packages !== 'object') return []
+
+  return Object.entries(packages as Record<string, unknown>).map(
+    ([name, value]) => {
+      const entry = (value ?? {}) as Record<string, unknown>
+      const parameters = Array.isArray(entry.parameters)
+        ? entry.parameters.filter((p): p is string => typeof p === 'string')
+        : undefined
+
+      return {
+        name,
+        source: typeof entry.source === 'string' ? entry.source : name,
+        version: typeof entry.version === 'string' ? entry.version : undefined,
+        parameters,
+      }
+    },
+  )
+}
+
+/**
+ * Walks up from `startDir` looking for a Pulumi.yaml/Pulumi.yml, then reads its
+ * `packages` section to find the local/parameterized providers used by the project.
+ */
+export function loadPulumiProject(
+  startDir: string = getTargetDir(),
+): PulumiProject | null {
+  const projectFile = findProjectFile(startDir)
+  if (!projectFile) return null
+
+  const raw = readFileSync(projectFile, 'utf-8')
+  const doc = parse(raw) as Record<string, unknown> | null
+
+  return {
+    root: dirname(projectFile),
+    name: typeof doc?.name === 'string' ? doc.name : undefined,
+    runtime:
+      typeof doc?.runtime === 'string'
+        ? doc.runtime
+        : typeof (doc?.runtime as Record<string, unknown> | undefined)?.name ===
+            'string'
+          ? ((doc!.runtime as Record<string, unknown>).name as string)
+          : undefined,
+    packages: toLocalPackageRefs(doc?.packages),
+  }
+}

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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  extractExamples,
+  pickExample,
+  stripExamples,
+  summarizeDescription,
+} from '@/lib/pulumi/examples'
+
+const DESCRIPTION = `Generates random bytes.
+
+## Example Usage
+
+\`\`\`typescript
+const bytes = new random.RandomBytes("bytes", {length: 32});
+\`\`\`
+\`\`\`python
+bytes = random.RandomBytes("bytes", length=32)
+\`\`\`
+\`\`\`go
+bytes, err := random.NewRandomBytes(ctx, "bytes", &random.RandomBytesArgs{Length: 32})
+\`\`\`
+`
+
+describe('extractExamples', () => {
+  it('returns an empty list for no description', () => {
+    expect(extractExamples(undefined)).toEqual([])
+  })
+
+  it('returns an empty list when there are no fenced code blocks', () => {
+    expect(extractExamples('just some prose')).toEqual([])
+  })
+
+  it('extracts each labeled code block', () => {
+    expect(extractExamples(DESCRIPTION)).toEqual([
+      {
+        language: 'typescript',
+        code: 'const bytes = new random.RandomBytes("bytes", {length: 32});',
+      },
+      {
+        language: 'python',
+        code: 'bytes = random.RandomBytes("bytes", length=32)',
+      },
+      {
+        language: 'go',
+        code: 'bytes, err := random.NewRandomBytes(ctx, "bytes", &random.RandomBytesArgs{Length: 32})',
+      },
+    ])
+  })
+})
+
+describe('stripExamples', () => {
+  it('removes fenced code blocks, leaving the prose', () => {
+    expect(stripExamples(DESCRIPTION)).toBe(
+      'Generates random bytes.\n\n## Example Usage',
+    )
+  })
+
+  it('returns undefined when nothing but code blocks remain', () => {
+    expect(stripExamples('```typescript\ncode\n```')).toBeUndefined()
+  })
+})
+
+describe('summarizeDescription', () => {
+  it('returns the first paragraph, examples excluded', () => {
+    expect(summarizeDescription(DESCRIPTION)).toBe('Generates random bytes.')
+  })
+
+  it('returns undefined for an empty description', () => {
+    expect(summarizeDescription(undefined)).toBeUndefined()
+  })
+})
+
+describe('pickExample', () => {
+  const examples = extractExamples(DESCRIPTION)
+
+  it('picks the example matching the runtime', () => {
+    expect(pickExample(examples, 'python')?.language).toBe('python')
+    expect(pickExample(examples, 'go')?.language).toBe('go')
+  })
+
+  it('maps nodejs to typescript', () => {
+    expect(pickExample(examples, 'nodejs')?.language).toBe('typescript')
+  })
+
+  it('falls back to the first example when the runtime has none', () => {
+    expect(pickExample(examples, 'dotnet')?.language).toBe('typescript')
+  })
+
+  it('falls back to the first example when no runtime is given', () => {
+    expect(pickExample(examples)?.language).toBe('typescript')
+  })
+
+  it('returns undefined for an empty example list', () => {
+    expect(pickExample([], 'python')).toBeUndefined()
+  })
+})

package/src/lib/pulumi/examples.ts

@@ -0,0 +1,55 @@
+/**
+ * The Pulumi package schema has no dedicated "examples" field — usage
+ * examples live as fenced, language-tagged code blocks embedded directly in
+ * a resource/function's markdown `description` (e.g. a "## Example Usage"
+ * section with one ```typescript/```python/```go/... block per language).
+ */
+export interface SchemaExample {
+  language: string
+  code: string
+}
+
+const CODE_FENCE_RE = /```([a-zA-Z0-9+#-]+)\n([\s\S]*?)```/g
+
+export function extractExamples(text?: string): SchemaExample[] {
+  if (!text) return []
+  return [...text.matchAll(CODE_FENCE_RE)].map((match) => ({
+    language: match[1].toLowerCase(),
+    code: match[2].trimEnd(),
+  }))
+}
+
+/** The description text with any fenced code examples removed. */
+export function stripExamples(text?: string): string | undefined {
+  if (!text) return text
+  const stripped = text.replace(CODE_FENCE_RE, '').trim()
+  return stripped || undefined
+}
+
+/** A short summary for list views: the first prose paragraph, examples excluded. */
+export function summarizeDescription(text?: string): string | undefined {
+  const stripped = stripExamples(text)
+  if (!stripped) return undefined
+  return stripped.split(/\n{2,}/)[0]?.trim() || undefined
+}
+
+const RUNTIME_LANGUAGES: Record<string, string[]> = {
+  nodejs: ['typescript', 'javascript'],
+  python: ['python'],
+  go: ['go', 'golang'],
+  dotnet: ['csharp'],
+  java: ['java'],
+  yaml: ['yaml'],
+}
+
+/** Picks the example matching the project's runtime, falling back to the first available one. */
+export function pickExample(
+  examples: SchemaExample[],
+  runtime?: string,
+): SchemaExample | undefined {
+  const languages = runtime ? RUNTIME_LANGUAGES[runtime] : undefined
+  const match = languages
+    ? examples.find((example) => languages.includes(example.language))
+    : undefined
+  return match ?? examples[0]
+}

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+
+import { formatType } from '@/lib/pulumi/format'
+
+describe('formatType', () => {
+  it('returns "any" for an undefined property', () => {
+    expect(formatType(undefined)).toBe('any')
+  })
+
+  it('returns "any" for a property with neither a type nor a $ref', () => {
+    expect(formatType({})).toBe('any')
+  })
+
+  it('returns the plain type for a scalar property', () => {
+    expect(formatType({ type: 'string' })).toBe('string')
+    expect(formatType({ type: 'boolean' })).toBe('boolean')
+  })
+
+  it('shortens a $ref to its last path segment', () => {
+    expect(
+      formatType({ $ref: '#/types/random:index/randomString:RandomString' }),
+    ).toBe('randomString:RandomString')
+  })
+
+  it('url-decodes the shortened $ref', () => {
+    expect(
+      formatType({
+        $ref: '#/resources/pulumi:providers:random%2FterraformConfig',
+      }),
+    ).toBe('pulumi:providers:random/terraformConfig')
+  })
+
+  it('formats an array of a scalar type', () => {
+    expect(formatType({ type: 'array', items: { type: 'string' } })).toBe(
+      'string[]',
+    )
+  })
+
+  it('formats an array of $ref items', () => {
+    expect(
+      formatType({
+        type: 'array',
+        items: { $ref: '#/types/random:index/randomString:RandomString' },
+      }),
+    ).toBe('randomString:RandomString[]')
+  })
+
+  it('falls back to "any" for an array with no items', () => {
+    expect(formatType({ type: 'array' })).toBe('array')
+  })
+})

package/src/lib/pulumi/format.ts

@@ -0,0 +1,11 @@
+import type { SchemaProperty } from '@/lib/pulumi/types'
+
+export function formatType(prop?: SchemaProperty): string {
+  if (!prop) return 'any'
+  if (prop.$ref) {
+    const short = prop.$ref.split('/').pop() ?? prop.$ref
+    return decodeURIComponent(short)
+  }
+  if (prop.type === 'array' && prop.items) return `${formatType(prop.items)}[]`
+  return prop.type ?? 'any'
+}

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

@@ -0,0 +1,343 @@
+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 {
+  extractExamples,
+  pickExample,
+  stripExamples,
+  summarizeDescription,
+} from '@/lib/pulumi/examples'
+import { formatType } from '@/lib/pulumi/format'
+import { formatPropertyName } from '@/lib/pulumi/naming'
+import { resolveProviderSchema } from '@/lib/pulumi/schema.server'
+import { tokenDisplayName } from '@/lib/pulumi/token'
+import type {
+  SchemaFunction,
+  SchemaProperty,
+  SchemaResource,
+} from '@/lib/pulumi/types'
+
+function textResult(data: unknown): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+}
+
+/** Loads a local provider's resolved schema, throwing a descriptive error a tool call can surface to the client. */
+async function requireProvider(
+  providerName: string,
+): Promise<ProviderDetail & { schema: NonNullable<ProviderDetail['schema']> }> {
+  const detail = await getProvider({ data: 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.`,
+    )
+  }
+  if (!detail.schema) {
+    throw new Error(
+      `Failed to load the schema for provider "${providerName}": ${detail.error ?? 'unknown error'}`,
+    )
+  }
+  return { ...detail, schema: detail.schema }
+}
+
+function summarizeMember(
+  token: string,
+  member: SchemaResource | SchemaFunction,
+  runtime?: string,
+) {
+  return {
+    token,
+    name: tokenDisplayName(token),
+    deprecated: Boolean(
+      'deprecationMessage' in member && member.deprecationMessage,
+    ),
+    summary: summarizeDescription(
+      resolveDescription(member.description, runtime),
+    ),
+  }
+}
+
+function formatProperties(
+  properties: Record<string, SchemaProperty> | undefined,
+  required: string[] | undefined,
+  runtime: string | undefined,
+) {
+  const requiredSet = new Set(required ?? [])
+  return Object.entries(properties ?? {}).map(([name, prop]) => ({
+    name: formatPropertyName(name, runtime),
+    type: formatType(prop),
+    required: requiredSet.has(name),
+    description: resolveDescription(prop.description, runtime),
+  }))
+}
+
+function memberDetail(
+  provider: string,
+  token: string,
+  description: string | undefined,
+  runtime: string | undefined,
+  inputs: ReturnType<typeof formatProperties>,
+  outputs: ReturnType<typeof formatProperties>,
+  deprecationMessage?: string,
+) {
+  const resolved = resolveDescription(description, runtime)
+  const example = pickExample(extractExamples(resolved), runtime)
+
+  return {
+    provider,
+    token,
+    name: tokenDisplayName(token),
+    deprecationMessage,
+    description: stripExamples(resolved),
+    example: example ?? null,
+    inputs,
+    outputs,
+  }
+}
+
+/**
+ * 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.
+ */
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: 'pulumi-package-docs',
+    version: '0.1.0',
+  })
+
+  server.registerTool(
+    'list_providers',
+    {
+      title: 'List local providers',
+      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()),
+  )
+
+  server.registerTool(
+    'list_resources',
+    {
+      title: 'List a provider’s resources',
+      description:
+        'List the resource tokens for a local provider, each with a display name, a one-line summary, and whether it is deprecated. Use get_resource for full details (inputs/outputs/example) on one of them.',
+      inputSchema: {
+        provider: z
+          .string()
+          .describe(
+            'The provider name as it appears in Pulumi.yaml and list_providers, e.g. "random".',
+          ),
+      },
+    },
+    async ({ provider }) => {
+      const detail = await requireProvider(provider)
+      const resources = Object.entries(detail.schema.resources ?? {}).map(
+        ([token, resource]) => summarizeMember(token, resource, detail.runtime),
+      )
+      return textResult({
+        provider,
+        resourceCount: resources.length,
+        resources,
+      })
+    },
+  )
+
+  server.registerTool(
+    'list_functions',
+    {
+      title: 'List a provider’s functions',
+      description:
+        'List the function (data source) tokens for a local provider, each with a display name, a one-line summary, and whether it is deprecated. Use get_function for full details (inputs/outputs/example) on one of them.',
+      inputSchema: {
+        provider: z
+          .string()
+          .describe(
+            'The provider name as it appears in Pulumi.yaml and list_providers, e.g. "random".',
+          ),
+      },
+    },
+    async ({ provider }) => {
+      const detail = await requireProvider(provider)
+      const functions = Object.entries(detail.schema.functions ?? {}).map(
+        ([token, fn]) => summarizeMember(token, fn, detail.runtime),
+      )
+      return textResult({
+        provider,
+        functionCount: functions.length,
+        functions,
+      })
+    },
+  )
+
+  server.registerTool(
+    'get_resource',
+    {
+      title: 'Get resource details',
+      description:
+        'Get the full documentation for one resource of a local provider: its description, a usage example (in the Pulumi project’s own language), and its input and output properties (name, type, required, description). Get the exact token from list_resources first.',
+      inputSchema: {
+        provider: z.string().describe('The provider name, e.g. "random".'),
+        token: z
+          .string()
+          .describe(
+            'The resource’s full schema token from list_resources, e.g. "random:index/randomString:RandomString".',
+          ),
+      },
+    },
+    async ({ provider, token }) => {
+      const detail = await requireProvider(provider)
+      const resource = detail.schema.resources?.[token]
+      if (!resource) {
+        throw new Error(
+          `No resource with token "${token}" in provider "${provider}". Call list_resources to find the exact token.`,
+        )
+      }
+      return textResult(
+        memberDetail(
+          provider,
+          token,
+          resource.description,
+          detail.runtime,
+          formatProperties(
+            resource.inputProperties,
+            resource.requiredInputs,
+            detail.runtime,
+          ),
+          formatProperties(
+            resource.properties,
+            resource.required,
+            detail.runtime,
+          ),
+          resource.deprecationMessage,
+        ),
+      )
+    },
+  )
+
+  server.registerTool(
+    'get_function',
+    {
+      title: 'Get function details',
+      description:
+        'Get the full documentation for one function (data source) of a local provider: its description, a usage example (in the Pulumi project’s own language), and its input and output properties. Get the exact token from list_functions first.',
+      inputSchema: {
+        provider: z.string().describe('The provider name, e.g. "random".'),
+        token: z
+          .string()
+          .describe(
+            'The function’s full schema token from list_functions, e.g. "random:index/randomInteger:getRandomInteger".',
+          ),
+      },
+    },
+    async ({ provider, token }) => {
+      const detail = await requireProvider(provider)
+      const fn = detail.schema.functions?.[token]
+      if (!fn) {
+        throw new Error(
+          `No function with token "${token}" in provider "${provider}". Call list_functions to find the exact token.`,
+        )
+      }
+      return textResult(
+        memberDetail(
+          provider,
+          token,
+          fn.description,
+          detail.runtime,
+          formatProperties(
+            fn.inputs?.properties,
+            fn.inputs?.required,
+            detail.runtime,
+          ),
+          formatProperties(
+            fn.outputs?.properties,
+            fn.outputs?.required,
+            detail.runtime,
+          ),
+        ),
+      )
+    },
+  )
+
+  server.registerTool(
+    'search_members',
+    {
+      title: 'Search resources and functions',
+      description:
+        'Search resource and function tokens/descriptions across one or all local providers for a keyword. Use this instead of list_resources/list_functions when a provider is large or you only know roughly what you’re looking for (e.g. "bucket", "random string").',
+      inputSchema: {
+        query: z.string().describe('Case-insensitive text to search for.'),
+        provider: z
+          .string()
+          .optional()
+          .describe(
+            'Limit the search to this provider name. Omit to search all local providers.',
+          ),
+      },
+    },
+    async ({ query, provider }) => {
+      const targetDir = getTargetDir()
+      const project = loadPulumiProject(targetDir)
+      if (!project) return textResult({ query, matchCount: 0, matches: [] })
+
+      const refs = provider
+        ? project.packages.filter((p) => p.name === provider)
+        : project.packages
+      if (provider && refs.length === 0) {
+        throw new Error(
+          `No local provider named "${provider}" was found. Call list_providers to see the providers declared in this project's Pulumi.yaml.`,
+        )
+      }
+
+      const needle = query.toLowerCase()
+      const matches: Array<{
+        provider: string
+        kind: 'resource' | 'function'
+        token: string
+        name: string
+        summary?: string
+      }> = []
+
+      for (const ref of refs) {
+        const entry = await resolveProviderSchema(project.root, ref)
+        if (!entry.schema) continue
+
+        const groups: Array<
+          [
+            kind: 'resource' | 'function',
+            members:
+              | Record<string, SchemaResource | SchemaFunction>
+              | undefined,
+          ]
+        > = [
+          ['resource', entry.schema.resources],
+          ['function', entry.schema.functions],
+        ]
+
+        for (const [kind, members] of groups) {
+          for (const [token, member] of Object.entries(members ?? {})) {
+            const name = tokenDisplayName(token)
+            const summary = summarizeDescription(
+              resolveDescription(member.description, project.runtime),
+            )
+            const haystack = `${name} ${token} ${summary ?? ''}`.toLowerCase()
+            if (haystack.includes(needle)) {
+              matches.push({ provider: ref.name, kind, token, name, summary })
+            }
+          }
+        }
+      }
+
+      return textResult({
+        query,
+        matchCount: matches.length,
+        matches: matches.slice(0, 50),
+      })
+    },
+  )
+
+  return server
+}

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { formatPropertyName } from '@/lib/pulumi/naming'
+
+describe('formatPropertyName', () => {
+  it('leaves the name as-is when no runtime is given', () => {
+    expect(formatPropertyName('bucketName')).toBe('bucketName')
+  })
+
+  it('leaves the name as-is for nodejs, java, and yaml', () => {
+    expect(formatPropertyName('bucketName', 'nodejs')).toBe('bucketName')
+    expect(formatPropertyName('bucketName', 'java')).toBe('bucketName')
+    expect(formatPropertyName('bucketName', 'yaml')).toBe('bucketName')
+  })
+
+  it('converts to snake_case for python', () => {
+    expect(formatPropertyName('bucketName', 'python')).toBe('bucket_name')
+    expect(formatPropertyName('s3BucketName', 'python')).toBe('s3_bucket_name')
+    expect(formatPropertyName('id', 'python')).toBe('id')
+  })
+
+  it('converts to PascalCase for go and dotnet', () => {
+    expect(formatPropertyName('bucketName', 'go')).toBe('BucketName')
+    expect(formatPropertyName('bucketName', 'dotnet')).toBe('BucketName')
+    expect(formatPropertyName('s3BucketName', 'go')).toBe('S3BucketName')
+  })
+})

package/src/lib/pulumi/naming.ts

@@ -0,0 +1,31 @@
+/**
+ * Pulumi schema property names are always camelCase; each language's generated
+ * SDK renders them in that language's own convention. This approximates that
+ * per-runtime rendering for display purposes (it doesn't reproduce Pulumi's
+ * codegen exactly, e.g. its acronym handling, but matches the common case).
+ */
+function toSnakeCase(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .toLowerCase()
+}
+
+function toPascalCase(name: string): string {
+  if (name.length === 0) return name
+  return name.charAt(0).toUpperCase() + name.slice(1)
+}
+
+/** Renders a schema property name the way it would appear in the given Pulumi runtime's generated SDK. */
+export function formatPropertyName(name: string, runtime?: string): string {
+  switch (runtime) {
+    case 'python':
+      return toSnakeCase(name)
+    case 'go':
+    case 'dotnet':
+      return toPascalCase(name)
+    // nodejs, java, and yaml all use the schema's camelCase names as-is.
+    default:
+      return name
+  }
+}