polen 0.10.0-next.3 → 0.10.0-next.4

package/src/cli/commands/static/$default.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { Arr, Cli, Path, Str } from '@wollybeard/kit'
+import $ from 'ansis'
+import console from 'console'
+
+const commandsDir = import.meta.dirname
+const thisModuleName = Path.parse(import.meta.filename).name
+const cliName = `polen static`
+
+const h2 = (str: string) => {
+  return $.bold.black.bgWhiteBright(` ${str.toUpperCase()} `)
+}
+
+const code = (str: string) => {
+  if (!$.isSupported()) return `\`${str}\``
+  return $.magenta(str)
+}
+
+const s = Str.Builder()
+const allCommands = await Cli.discoverCommandPointers(commandsDir)
+const commands = allCommands.filter(_ => _.name !== thisModuleName)
+
+s``
+s`${$.bold.redBright`POLEN 🌺`} ${$.dim(`static commands`)}`
+s`Manage static builds and deployments.`
+s``
+s``
+s`${h2(`commands`)}`
+s``
+
+if (Arr.isEmpty(commands)) {
+  s`No commands available yet.`
+} else {
+  commands.forEach(command => {
+    s`${$.dim`$ ${cliName}`} ${$.cyanBright(command.name)}`
+  })
+}
+s``
+s`${$.dim`Get help for a command with ${code(`polen static <command> --help`)}`}`
+s``
+
+console.log(Str.indent(String(s)))

package/src/cli/commands/static/rebase.ts

@@ -0,0 +1,37 @@
+/* eslint-disable */
+// @ts-nocheck
+import { Api } from '#api/index'
+import { Task } from '#lib/task'
+import { Command } from '@molt/command'
+import { Err, Path } from '@wollybeard/kit'
+import { z } from 'zod'
+
+const args = Command.create()
+  .parameter(
+    `source`,
+    z.string().describe('Path to the Polen build directory to rebase'),
+  )
+  .parameter(
+    `newBasePath`,
+    z.string().describe('New base path for the build (e.g., /new-path/)'),
+  )
+  .parameter(
+    `--target -t`,
+    z.string().optional().describe('Target directory for copy mode (if not provided, mutate in place)'),
+  )
+  .parse()
+
+const plan: Api.Static.RebasePlan = args.target
+  ? {
+    changeMode: 'copy',
+    sourcePath: args.source,
+    targetPath: args.target,
+    newBasePath: args.newBasePath,
+  }
+  : {
+    changeMode: 'mutate',
+    sourcePath: args.source,
+    newBasePath: args.newBasePath,
+  }
+
+await Task.runAndExit(Api.Static.rebase, plan)

package/src/cli/commands/static.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { Cli, Path } from '@wollybeard/kit'
+
+const commandsDir = Path.join(import.meta.dirname, 'static')
+await Cli.dispatch(commandsDir)

package/src/lib/demos/builder.ts

@@ -0,0 +1,298 @@
+import { promises as fs } from 'node:fs'
+import * as path from 'node:path'
+import { $ } from 'zx'
+import { getDemoConfig } from './config.ts'
+import { getDemoExamples } from './utils.ts'
+
+// Configure zx for CI-friendly operation
+$.verbose = true // Show command output
+$.quiet = false // Don't suppress stdout/stderr
+
+export interface BuildOptions {
+  basePath?: string
+  outputDir?: string
+  examples?: string[]
+  prNumber?: string
+  currentSha?: string
+}
+
+export interface DeployOptions {
+  sourceDir: string
+  targetDir: string
+  updateBasePaths?: {
+    from: string
+    to: string
+  }
+}
+
+export class DemoBuilder {
+  private config = getDemoConfig()
+
+  /**
+   * Build demos for a specific version/tag
+   */
+  async build(tag: string, options: BuildOptions = {}): Promise<void> {
+    const basePath = options.basePath || `/polen/${tag}/`
+    const examples = options.examples || await getDemoExamples()
+
+    for (const example of examples) {
+      await this.buildExample(example, `${basePath}${example}/`, options.outputDir)
+    }
+  }
+
+  // /**
+  //  * Build demos landing page
+  //  */
+  // private async buildLandingPage(options: {
+  //   basePath: string
+  //   outputDir?: string
+  //   prNumber?: string
+  //   currentSha?: string
+  // }): Promise<void> {
+  //   console.log(`  Building landing page...`)
+
+  //   // Import and call the build-demos-home module directly
+  //   const { buildDemosHome } = await import('./ui/landing-page.ts')
+
+  //   await buildDemosHome({
+  //     basePath: options.basePath || '/',
+  //     prNumber: options.prNumber,
+  //     currentSha: options.currentSha,
+  //     prDeployments: undefined,
+  //     trunkDeployments: undefined,
+  //     distTags: undefined,
+  //   })
+  // }
+
+  /**
+   * Build a single example
+   */
+  private async buildExample(
+    example: string,
+    basePath: string,
+    outputDir?: string,
+  ): Promise<void> {
+    const exampleDir = path.join('examples', example)
+
+    // Check if example exists
+    try {
+      await fs.access(exampleDir)
+    } catch {
+      console.warn(`  ⚠️  Example ${example} not found, skipping`)
+      return
+    }
+
+    console.log(`  Building ${example}...`)
+
+    // Build using Polen CLI
+    const args = ['build', '--base', basePath]
+    if (outputDir) {
+      args.push('--outputDir', path.join(outputDir, example))
+    }
+
+    // Build with a timeout to prevent hanging
+    try {
+      // Use --yes to auto-confirm any npx prompts and set CI env
+      await $`cd ${exampleDir} && CI=true npx --yes polen ${args}`.timeout('5m')
+      console.log(`  ✅ Built ${example}`)
+    } catch (error) {
+      console.error(`  ❌ Failed to build ${example}:`, error)
+      throw error
+    }
+  }
+
+  /**
+   * Deploy built demos to a target directory
+   */
+  async deploy(options: DeployOptions): Promise<void> {
+    const { sourceDir, targetDir, updateBasePaths } = options
+
+    console.log(`🚀 Deploying demos from ${sourceDir} to ${targetDir}`)
+
+    // Ensure target directory exists and is clean
+    await fs.rm(targetDir, { recursive: true, force: true })
+    await fs.mkdir(targetDir, { recursive: true })
+
+    // Copy demos landing page if it exists
+    const landingPageSrc = path.join(sourceDir, 'index.html')
+    try {
+      await fs.access(landingPageSrc)
+      await fs.copyFile(landingPageSrc, path.join(targetDir, 'index.html'))
+      console.log(`  Copied landing page`)
+    } catch {
+      // Check dist-demos-home directory as alternative source
+      try {
+        const altLandingPage = path.join('dist-demos-home', 'index.html')
+        await fs.access(altLandingPage)
+        await fs.copyFile(altLandingPage, path.join(targetDir, 'index.html'))
+        console.log(`  Copied landing page from dist-demos-home`)
+      } catch {
+        console.log(`  No landing page found`)
+      }
+    }
+
+    // Copy each example's build output
+    const examples = await getDemoExamples()
+    for (const example of examples) {
+      const buildDir = path.join('examples', example, 'build')
+      const destDir = path.join(targetDir, example)
+
+      try {
+        await fs.access(buildDir)
+        await fs.mkdir(destDir, { recursive: true })
+        await this.copyDirectory(buildDir, destDir)
+        console.log(`  Copied ${example}`)
+      } catch {
+        console.warn(`  ⚠️  No build output for ${example}, skipping`)
+      }
+    }
+
+    // Update base paths if needed
+    if (updateBasePaths) {
+      await this.updateBasePaths(targetDir, updateBasePaths.from, updateBasePaths.to)
+      console.log(`  Updated base paths from ${updateBasePaths.from} to ${updateBasePaths.to}`)
+    }
+
+    console.log(`✅ Successfully deployed demos to ${targetDir}`)
+  }
+
+  /**
+   * Copy directory recursively
+   */
+  private async copyDirectory(src: string, dest: string): Promise<void> {
+    await $`cp -r ${src}/* ${dest}/`
+  }
+
+  /**
+   * Update base paths in deployed files
+   */
+  async updateBasePaths(
+    dir: string,
+    oldPath: string,
+    newPath: string,
+  ): Promise<void> {
+    // Find all HTML, JS, CSS, and JSON files and update paths
+    await $`find ${dir} -type f \\( -name "*.html" -o -name "*.js" -o -name "*.css" -o -name "*.json" \\) | while read file; do
+      perl -i -pe "s|${oldPath.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')}|${newPath}|g" "$file"
+    done`
+  }
+
+  /**
+   * Build and deploy demos for multiple versions
+   *
+   * This method automates the process of building demos for multiple Polen versions:
+   *
+   * 1. For each version tag (e.g., "1.2.0", "1.3.0-beta.1"):
+   *    - Checks out that git tag to get the code at that version
+   *    - Builds Polen itself (pnpm build)
+   *    - Builds all demo examples using that version of Polen
+   *    - Deploys the built demos to deployDir/[version]/
+   *
+   * 2. Handles version filtering:
+   *    - Skips versions below the configured minimumPolenVersion
+   *    - Skips versions where Polen build fails
+   *
+   * 3. Git branch management:
+   *    - By default, saves and restores the original branch when done
+   *    - This prevents leaving the repo in a detached HEAD state
+   *    - Set restoreOriginalBranch: false to disable this behavior
+   *
+   * Example:
+   * ```
+   * // Build demos for versions 1.2.0 and 1.3.0-beta.1
+   * const results = await buildMultipleVersions(
+   *   ['1.2.0', '1.3.0-beta.1'],
+   *   'gh-pages'
+   * )
+   * // Results: { built: ['1.2.0', '1.3.0-beta.1'], skipped: [] }
+   * ```
+   *
+   * Note: This method modifies the git working directory by checking out tags.
+   * The original branch is restored by default to prevent issues in CI environments.
+   */
+  async buildMultipleVersions(
+    versions: string[],
+    deployDir: string,
+    options: { restoreOriginalBranch?: boolean } = { restoreOriginalBranch: true },
+  ): Promise<{ built: string[]; skipped: string[] }> {
+    const results = {
+      built: [] as string[],
+      skipped: [] as string[],
+    }
+
+    // Save current branch if needed
+    let originalBranch: string | null = null
+    if (options.restoreOriginalBranch !== false) {
+      originalBranch = (await $`git rev-parse --abbrev-ref HEAD`).stdout.trim()
+    }
+
+    try {
+      for (const version of versions) {
+        // Skip if below minimum Polen version
+        if (!this.config.meetsMinimumPolenVersion(version)) {
+          console.log(
+            `⚠️ Skipping ${version} - below minimum Polen version ${this.config.minimumPolenVersion}`,
+          )
+          results.skipped.push(version)
+          continue
+        }
+
+        console.log(`\n📦 Building ${version}...`)
+
+        // Checkout the version
+        await $`git checkout ${version}`
+
+        // Build Polen
+        try {
+          await $`pnpm build`
+        } catch {
+          console.log(`⚠️ Could not build Polen for ${version}, skipping`)
+          results.skipped.push(version)
+          continue
+        }
+
+        // Re-install to link workspace packages
+        await $`pnpm install`
+
+        // Build demos
+        await this.build(version)
+
+        // Determine target directory
+        // Stable versions go to version-specific dirs (not 'latest' here)
+        const targetDir = path.join(deployDir, version)
+
+        await this.deploy({
+          sourceDir: 'dist-demos',
+          targetDir,
+        })
+
+        results.built.push(version)
+      }
+    } finally {
+      // Restore original branch if requested (default behavior)
+      if (originalBranch && options.restoreOriginalBranch !== false) {
+        await $`git checkout ${originalBranch}`
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Build demos for current development cycle
+   */
+  async buildCurrentCycle(deployDir: string): Promise<void> {
+    const { VersionHistory } = await import('../version-history/index.ts')
+    const cycle = await VersionHistory.getCurrentDevelopmentCycle()
+
+    if (!cycle.stable) {
+      throw new Error('No stable release found')
+    }
+
+    const versions = cycle.all.map(v => v.git.tag)
+    await this.buildMultipleVersions(versions, deployDir)
+  }
+}
+
+// Export singleton instance
+export const demoBuilder = new DemoBuilder()

package/src/lib/demos/config-schema.ts

@@ -0,0 +1,56 @@
+/**
+ * Schema definitions for demo configuration
+ */
+
+import { z } from 'zod'
+
+// Schema for demo configuration
+export const DemoConfigSchema = z.object({
+  examples: z.object({
+    exclude: z.array(z.string()).default([]),
+    order: z.array(z.string()).default([]),
+    minimumPolenVersion: z.string().default('0.1.0'),
+  }),
+  deployment: z.object({
+    basePaths: z.record(z.string()).default({}),
+    redirects: z.array(z.object({
+      from: z.string(),
+      to: z.string(),
+    })).default([]),
+    gc: z.object({
+      retainStableVersions: z.boolean().default(true),
+      retainCurrentCycle: z.boolean().default(true),
+      retainDays: z.number().default(30),
+    }).default({}),
+  }),
+  ui: z.object({
+    theme: z.object({
+      primaryColor: z.string().default('#000'),
+      backgroundColor: z.string().default('#fff'),
+      textColor: z.string().default('#000'),
+      mutedTextColor: z.string().default('#666'),
+    }).default({}),
+    branding: z.object({
+      title: z.string().default('Polen Demos'),
+      description: z.string().default('Interactive GraphQL API documentation'),
+      logoUrl: z.string().optional(),
+    }).default({}),
+  }),
+  metadata: z.object({
+    disabledDemos: z.record(z.object({
+      title: z.string(),
+      description: z.string(),
+      reason: z.string().optional(),
+    })).default({}),
+  }),
+})
+
+export type DemoConfigData = z.infer<typeof DemoConfigSchema>
+
+// Legacy schema for backward compatibility
+export const LegacyDemoConfigSchema = z.object({
+  excludeDemos: z.array(z.string()).optional(),
+  minimumVersion: z.string().optional(),
+  minimumPolenVersion: z.string().optional(),
+  order: z.array(z.string()).optional(),
+})

package/src/lib/demos/config.test.ts

@@ -0,0 +1,193 @@
+import { readFileSync } from 'node:fs'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DemoConfig, getDemoConfig, resetDemoConfig } from './config.ts'
+
+vi.mock('node:fs', () => ({
+  readFileSync: vi.fn(),
+}))
+
+// Mock the imported TypeScript config to prevent it from affecting tests
+vi.mock('../../../.github/demo-config.ts', () => ({
+  default: null,
+}))
+
+describe('DemoConfig', () => {
+  const mockReadFileSync = readFileSync as unknown as ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    // Reset singleton
+    resetDemoConfig()
+  })
+
+  describe('constructor', () => {
+    it('loads config from default path', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        excludeDemos: ['test1', 'test2'],
+        minimumPolenVersion: '1.0.0',
+        order: ['demo1', 'demo2'],
+      }))
+
+      const config = new DemoConfig()
+
+      expect(mockReadFileSync).toHaveBeenCalledWith('.github/demo-config.json', 'utf-8')
+      expect(config.excludeDemos).toEqual(['test1', 'test2'])
+      expect(config.minimumPolenVersion).toBe('1.0.0')
+      expect(config.order).toEqual(['demo1', 'demo2'])
+    })
+
+    it('loads config from custom path', () => {
+      mockReadFileSync.mockReturnValue('{}')
+
+      const config = new DemoConfig('custom/path')
+
+      expect(mockReadFileSync).toHaveBeenCalledWith('custom/path.json', 'utf-8')
+    })
+
+    it('uses defaults when config file is missing', () => {
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error('File not found')
+      })
+
+      const config = new DemoConfig()
+
+      expect(config.excludeDemos).toEqual([])
+      expect(config.minimumPolenVersion).toBe('0.1.0')
+      expect(config.order).toEqual([])
+    })
+
+    it('supports legacy minimumVersion field', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        minimumVersion: '0.8.0', // old field name
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.minimumPolenVersion).toBe('0.8.0')
+    })
+
+    it('prefers minimumPolenVersion over minimumVersion', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        minimumVersion: '0.8.0',
+        minimumPolenVersion: '0.9.0',
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.minimumPolenVersion).toBe('0.9.0')
+    })
+  })
+
+  describe('meetsMinimumPolenVersion', () => {
+    it('returns true when version meets minimum', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        minimumPolenVersion: '1.0.0',
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.meetsMinimumPolenVersion('1.0.0')).toBe(true)
+      expect(config.meetsMinimumPolenVersion('1.0.1')).toBe(true)
+      expect(config.meetsMinimumPolenVersion('2.0.0')).toBe(true)
+    })
+
+    it('returns false when version is below minimum', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        minimumPolenVersion: '1.0.0',
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.meetsMinimumPolenVersion('0.9.0')).toBe(false)
+      expect(config.meetsMinimumPolenVersion('0.9.9')).toBe(false)
+    })
+
+    it('returns false for invalid versions', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        minimumPolenVersion: '1.0.0',
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.meetsMinimumPolenVersion('invalid')).toBe(false)
+      expect(config.meetsMinimumPolenVersion('')).toBe(false)
+    })
+  })
+
+  describe('isDemoExcluded', () => {
+    it('returns true for excluded demos', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        excludeDemos: ['demo1', 'demo2'],
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.isDemoExcluded('demo1')).toBe(true)
+      expect(config.isDemoExcluded('demo2')).toBe(true)
+    })
+
+    it('returns false for non-excluded demos', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        excludeDemos: ['demo1'],
+      }))
+
+      const config = new DemoConfig()
+
+      expect(config.isDemoExcluded('demo3')).toBe(false)
+    })
+  })
+
+  describe('getOrderedDemos', () => {
+    it('orders demos according to config', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        excludeDemos: ['excluded1'],
+        order: ['demo3', 'demo1'],
+      }))
+
+      const config = new DemoConfig()
+      const availableDemos = ['demo1', 'demo2', 'demo3', 'demo4', 'excluded1']
+
+      const ordered = config.getOrderedDemos(availableDemos)
+
+      expect(ordered).toEqual(['demo3', 'demo1', 'demo2', 'demo4'])
+    })
+
+    it('handles demos in order that are not available', () => {
+      mockReadFileSync.mockReturnValue(JSON.stringify({
+        order: ['demo1', 'nonexistent', 'demo2'],
+      }))
+
+      const config = new DemoConfig()
+      const availableDemos = ['demo1', 'demo2', 'demo3']
+
+      const ordered = config.getOrderedDemos(availableDemos)
+
+      expect(ordered).toEqual(['demo1', 'demo2', 'demo3'])
+    })
+  })
+
+  describe('getDemoConfig singleton', () => {
+    it('returns same instance on multiple calls', () => {
+      mockReadFileSync.mockReturnValue('{}')
+
+      const config1 = getDemoConfig()
+      const config2 = getDemoConfig()
+
+      expect(config1).toBe(config2)
+      expect(mockReadFileSync).toHaveBeenCalledTimes(1)
+    })
+
+    it('creates new instance when path is provided', () => {
+      mockReadFileSync.mockReturnValue('{}')
+
+      const config1 = getDemoConfig()
+      const config2 = getDemoConfig('custom/path.json')
+
+      expect(config1).not.toBe(config2)
+      expect(mockReadFileSync).toHaveBeenCalledTimes(2)
+    })
+  })
+})