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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.10.0-next.3",
+  "version": "0.10.0-next.4",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -35,7 +35,13 @@
     "#*": {
       "source": "./src/*.ts",
       "default": "./build/*.js"
-    }
+    },
+    "#lib/mask": "./src/lib/mask/$.ts",
+    "#lib/mask/mask": "./src/lib/mask/$$.ts",
+    "#lib/task": "./src/lib/task/$.ts",
+    "#lib/task/task": "./src/lib/task/$$.ts",
+    "#lib/deployment": "./src/lib/deployment/$.ts",
+    "#lib/deployment/deployment": "./src/lib/deployment/$$.ts"
   },
   "exports": {
     ".": {
@@ -86,8 +92,9 @@
     "@types/jsesc": "^3.0.3",
     "@vitejs/plugin-react": "^4.5.2",
     "@vitejs/plugin-react-oxc": "^0.2.3",
+    "@vltpkg/semver": "0.0.0-15",
     "@vue/reactivity": "^3.5.16",
-    "@wollybeard/kit": "^0.36.0",
+    "@wollybeard/kit": "^0.40.0",
     "@wollybeard/projector": "^0.2.0",
     "ansis": "^4.1.0",
     "clean-stack": "^5.2.0",
@@ -112,6 +119,7 @@
     "resolve.imports": "^2.0.3",
     "rolldown": "1.0.0-beta.16",
     "shiki": "^3.6.0",
+    "simple-git": "^3.28.0",
     "source-map": "^0.7.4",
     "superjson": "^2.2.2",
     "tinyglobby": "^0.2.14",
@@ -156,6 +164,7 @@
     "eslint-plugin-react-refresh": "^0.4.20",
     "eslint-plugin-tsdoc": "^0.4.0",
     "eslint-plugin-unused-imports": "^4.1.4",
+    "fast-check": "^4.1.1",
     "fs-jetpack": "^5.1.0",
     "get-port-please": "^3.1.2",
     "globals": "^16.2.0",
@@ -168,14 +177,10 @@
     "typescript-eslint": "^8.34.1",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.3",
-    "zod": "^3.25.65"
+    "zod": "3.25.67"
   },
   "packageManager": "pnpm@10.11.1",
   "scripts": {
-    "gh:demos-rebuild": "gh workflow run demos-rebuild.yaml -f since_version=0.9.0-next.8",
-    "gh:demos-rebuild:list": "gh run list --workflow=demos-rebuild.yaml",
-    "gh:demos-rebuild:logs": "gh run view $(gh run list --workflow=demos-rebuild.yaml --limit=1 --json databaseId -q '.[0].databaseId') --log",
-    "gh:demos-rebuild:watch": "gh run watch $(gh run list --workflow=demos-rebuild.yaml --limit=1 --json databaseId -q '.[0].databaseId')",
     "sandbox": "tsx src/sandbox",
     "sandbox:watch": "tsx --watch src/sandbox",
     "sb": "pnpm sandbox",
@@ -186,7 +191,9 @@
     "test:unit": "vitest",
     "dev": "pnpm build:watch:emit",
     "dev:pokemon": "pnpm polen dev --project examples/pokemon",
-    "dev:demo-index": "node --no-warnings ./scripts/build-demos-index.ts --mode dev --serve",
+    "dev:hive": "pnpm polen dev --project examples/hive",
+    "dev:github": "pnpm polen dev --project examples/github",
+    "dev:demo-index": "node --no-warnings --experimental-transform-types --conditions source ./src/lib/demos/ui/landing-page-cli.ts --mode dev --serve",
     "build:demos": "zx ./scripts/build-demos.mjs",
     "build:clean": "pnpm tsc --build tsconfig.build.json --clean && rm -rf build",
     "build": "tsc --build tsconfig.build.json",

package/src/api/api.ts

@@ -1,3 +1,4 @@
 export * from './builder/index.ts'
 export * from './config-resolver/index.ts'
 export * from './config/index.ts'
+export * from './static/index.ts'

package/src/api/singletons/markdown/markdown.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { parse } from './markdown.js'
+import { parse } from './markdown.ts'
 
 describe(`markdown parser with syntax highlighting`, () => {
   test(`parse highlights code blocks`, async () => {

package/src/api/static/index.ts

@@ -0,0 +1 @@
+export * as Static from './static.ts'

package/src/api/static/manifest.test.ts

@@ -0,0 +1,106 @@
+import { Err, Fs, Path } from '@wollybeard/kit'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { buildManifest, type PolenBuildManifest } from './manifest.ts'
+
+describe('validate-build', () => {
+  let testDir: string
+  let manifestPath: string
+
+  beforeEach(async () => {
+    testDir = await Fs.makeTemporaryDirectory()
+    manifestPath = Path.join(testDir, '.polen', 'build.json')
+  })
+
+  afterEach(async () => {
+    if (testDir && await Fs.exists(testDir)) {
+      await Fs.remove(testDir)
+    }
+  })
+
+  describe('readBuildManifest', () => {
+    test('reads valid manifest', async () => {
+      const manifest: PolenBuildManifest = {
+        type: 'ssr',
+        version: '2.1.0',
+        basePath: '/docs/',
+      }
+      await Fs.write({
+        path: manifestPath,
+        content: JSON.stringify(manifest, null, 2),
+      })
+
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(false)
+      expect(result).toEqual(manifest)
+    })
+
+    test('returns error when manifest does not exist', async () => {
+      // Verify the file doesn't exist
+      const manifestExists = await Fs.exists(manifestPath)
+      expect(manifestExists).toBe(false)
+
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(true)
+    })
+
+    test('returns error for invalid manifest structure', async () => {
+      await Fs.write({
+        path: manifestPath,
+        content: JSON.stringify({ invalid: 'data' }, null, 2),
+      })
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(true)
+    })
+
+    test('returns error for invalid build type', async () => {
+      await Fs.write({
+        path: manifestPath,
+        content: JSON.stringify(
+          {
+            type: 'invalid',
+            version: '1.0.0',
+            basePath: '/',
+          },
+          null,
+          2,
+        ),
+      })
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(true)
+    })
+
+    test('returns error when version is not a string', async () => {
+      await Fs.write({
+        path: manifestPath,
+        content: JSON.stringify(
+          {
+            type: 'ssg',
+            version: 123,
+            basePath: '/',
+          },
+          null,
+          2,
+        ),
+      })
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(true)
+    })
+
+    test('returns error when basePath is not a string', async () => {
+      await Fs.write({
+        path: manifestPath,
+        content: JSON.stringify(
+          {
+            type: 'ssg',
+            version: '1.0.0',
+            basePath: null,
+          },
+          null,
+          2,
+        ),
+      })
+      const result = await buildManifest.read(testDir)
+      expect(Err.is(result)).toBe(true)
+    })
+  })
+})

package/src/api/static/manifest.ts

@@ -0,0 +1,16 @@
+import { Codec, Resource } from '@wollybeard/kit'
+import { z } from 'zod/v4'
+
+export const PolenBuildManifestSchema = z.object({
+  type: z.enum(['ssg', 'ssr']),
+  version: z.string(),
+  basePath: z.string(),
+}).loose()
+
+export type PolenBuildManifest = z.infer<typeof PolenBuildManifestSchema>
+
+export const buildManifest = Resource.create({
+  name: 'polen-build-manifest',
+  path: '.polen/build.json',
+  codec: Codec.fromZod(PolenBuildManifestSchema),
+})

package/src/api/static/rebase.test.ts

@@ -0,0 +1,229 @@
+import { Fs, Path } from '@wollybeard/kit'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { rebase, type RebasePlan } from './rebase.ts'
+
+const testDir = 'temp/rebase-test'
+
+const createTestBuild = async (dir: string, basePath: string = '/') => {
+  await Fs.makeDirectory(dir)
+
+  // Create Polen build manifest
+  const polenDir = Path.join(dir, '.polen')
+  await Fs.makeDirectory(polenDir)
+
+  const manifest = {
+    type: 'ssg' as const,
+    version: '1.0.0',
+    basePath,
+  }
+
+  await Fs.write({
+    path: Path.join(polenDir, 'build.json'),
+    content: JSON.stringify(manifest, null, 2),
+  })
+
+  // Create some HTML files
+  await Fs.write({
+    path: Path.join(dir, 'index.html'),
+    content: `<!DOCTYPE html>
+<html>
+<head>
+  <base href="${basePath}">
+  <title>Test</title>
+</head>
+<body>
+  <h1>Test Page</h1>
+</body>
+</html>`,
+  })
+
+  // Create nested HTML file
+  const nestedDir = Path.join(dir, 'docs')
+  await Fs.makeDirectory(nestedDir)
+
+  await Fs.write({
+    path: Path.join(nestedDir, 'page.html'),
+    content: `<!DOCTYPE html>
+<html>
+<head>
+  <title>Nested</title>
+</head>
+<body>
+  <h1>Nested Page</h1>
+</body>
+</html>`,
+  })
+}
+
+describe('rebase', () => {
+  beforeEach(async () => {
+    await Fs.remove(testDir)
+  })
+
+  afterEach(async () => {
+    await Fs.remove(testDir)
+  })
+
+  test('mutate mode updates base paths in place', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    await createTestBuild(buildDir, '/old/')
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      newBasePath: '/new/',
+      changeMode: 'mutate',
+    }
+
+    await rebase(plan)
+
+    // Check updated manifest
+    const manifest = await Fs.readJson(Path.join(buildDir, '.polen', 'build.json'))
+    expect(manifest).toMatchObject({
+      type: 'ssg',
+      version: '1.0.0',
+      basePath: '/new/',
+    })
+
+    // Check updated HTML file
+    const indexContent = await Fs.read(Path.join(buildDir, 'index.html'))
+    expect(indexContent).toContain('<base href="/new/">')
+
+    // Check nested HTML file (should have base tag inserted)
+    const nestedContent = await Fs.read(Path.join(buildDir, 'docs', 'page.html'))
+    expect(nestedContent).toContain('<base href="/new/">')
+  })
+
+  test('copy mode creates new build with updated base paths', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    const copyDir = Path.join(testDir, 'copy')
+
+    await createTestBuild(buildDir, '/old/')
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      targetPath: copyDir,
+      newBasePath: '/new/',
+      changeMode: 'copy',
+    }
+
+    await rebase(plan)
+
+    // Original should be unchanged
+    const originalManifest = await Fs.readJson(Path.join(buildDir, '.polen', 'build.json'))
+    expect(originalManifest).toMatchObject({
+      basePath: '/old/',
+    })
+
+    // Copy should be updated
+    const copyManifest = await Fs.readJson(Path.join(copyDir, '.polen', 'build.json'))
+    expect(copyManifest).toMatchObject({
+      basePath: '/new/',
+    })
+
+    const copyIndexContent = await Fs.read(Path.join(copyDir, 'index.html'))
+    expect(copyIndexContent).toContain('<base href="/new/">')
+  })
+
+  test('throws error for invalid base path', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    await createTestBuild(buildDir)
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      newBasePath: 'invalid-path',
+      changeMode: 'mutate',
+    }
+
+    await expect(rebase(plan)).rejects.toThrow('Invalid base path: invalid-path')
+  })
+
+  test('throws error when source is not a Polen build', async () => {
+    const buildDir = Path.join(testDir, 'not-polen')
+    await Fs.makeDirectory(buildDir)
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      newBasePath: '/new/',
+      changeMode: 'mutate',
+    }
+
+    await expect(rebase(plan)).rejects.toThrow('Polen build manifest not found')
+  })
+
+  test('throws error when copy target exists and is not empty', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    const copyDir = Path.join(testDir, 'copy')
+
+    await createTestBuild(buildDir)
+
+    // Create non-empty target
+    await Fs.makeDirectory(copyDir)
+    await Fs.write({
+      path: Path.join(copyDir, 'existing.txt'),
+      content: 'existing file',
+    })
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      targetPath: copyDir,
+      newBasePath: '/new/',
+      changeMode: 'copy',
+    }
+
+    await expect(rebase(plan)).rejects.toThrow('Target path already exists and is not empty')
+  })
+
+  test('handles HTML file without existing base tag', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    await createTestBuild(buildDir)
+
+    // Create HTML without base tag
+    await Fs.write({
+      path: Path.join(buildDir, 'no-base.html'),
+      content: `<!DOCTYPE html>
+<html>
+<head>
+  <title>No Base</title>
+</head>
+<body>
+  <h1>No Base Tag</h1>
+</body>
+</html>`,
+    })
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      newBasePath: '/new/',
+      changeMode: 'mutate',
+    }
+
+    await rebase(plan)
+
+    const content = await Fs.read(Path.join(buildDir, 'no-base.html'))
+    expect(content).toContain('<base href="/new/">')
+  })
+
+  test('throws error for HTML file without head tag', async () => {
+    const buildDir = Path.join(testDir, 'build')
+    await createTestBuild(buildDir)
+
+    // Create invalid HTML without head
+    await Fs.write({
+      path: Path.join(buildDir, 'invalid.html'),
+      content: `<!DOCTYPE html>
+<html>
+<body>
+  <h1>Invalid HTML</h1>
+</body>
+</html>`,
+    })
+
+    const plan: RebasePlan = {
+      sourcePath: buildDir,
+      newBasePath: '/new/',
+      changeMode: 'mutate',
+    }
+
+    await expect(rebase(plan)).rejects.toThrow('Could not find <head> tag in HTML file')
+  })
+})

package/src/api/static/rebase.ts

@@ -0,0 +1,140 @@
+import { TinyGlobby } from '#dep/tiny-globby/index'
+import { Fs, Path } from '@wollybeard/kit'
+import { Err } from '@wollybeard/kit'
+import { buildManifest, type PolenBuildManifest } from './manifest.ts'
+
+export type RebasePlan = RebaseOverwritePlan | RebaseCopyPlan
+
+export interface RebaseOverwritePlan {
+  changeMode: 'mutate'
+  newBasePath: string
+  sourcePath: string
+}
+
+export interface RebaseCopyPlan {
+  changeMode: 'copy'
+  newBasePath: string
+  sourcePath: string
+  targetPath: string
+}
+
+export const rebase = async (plan: RebasePlan): Promise<void> => {
+  // 1. Validate source is a Polen build
+  const manifestResult = await buildManifest.read(plan.sourcePath)
+  if (Err.is(manifestResult)) {
+    throw new Error(`Polen build manifest not found at: ${Path.join(plan.sourcePath, '.polen', 'build.json')}`)
+  }
+  const manifest = manifestResult
+
+  // 2. Validate newBasePath is valid URL path
+  if (!isValidUrlPath(plan.newBasePath)) {
+    throw new Error(`Invalid base path: ${plan.newBasePath}`)
+  }
+
+  // 3. Handle copy vs mutate
+  let workingPath: string
+  if (plan.changeMode === 'copy') {
+    if (await Fs.exists(plan.targetPath)) {
+      const isEmpty = await Fs.isEmptyDir(plan.targetPath)
+      if (!isEmpty) {
+        throw new Error(`Target path already exists and is not empty: ${plan.targetPath}`)
+      }
+    }
+    await Fs.copyDir({ from: plan.sourcePath, to: plan.targetPath })
+    workingPath = plan.targetPath
+  } else {
+    workingPath = plan.sourcePath
+  }
+
+  // 4. Update HTML files with new base path
+  await updateHtmlFiles(workingPath, manifest.basePath, plan.newBasePath)
+
+  // 5. Update manifest
+  await updateManifest(workingPath, { basePath: plan.newBasePath })
+}
+
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Local Helpers
+//
+//
+
+// TODO: this is very generic, factor out to kit-temp
+const isValidUrlPath = (path: string): boolean => {
+  // URL path should start with / and not contain invalid characters
+  if (!path.startsWith('/')) return false
+  if (!path.endsWith('/')) return false
+
+  // Basic validation - no spaces, proper URL characters
+  const urlPathRegex = /^\/[a-zA-Z0-9\-._~:/?#[\]@!$&'()*+,;=%]*\/$/
+  return urlPathRegex.test(path)
+}
+
+const updateHtmlFiles = async (buildPath: string, oldBasePath: string, newBasePath: string): Promise<void> => {
+  // Find all HTML files recursively
+  const htmlFiles = await findHtmlFiles(buildPath)
+
+  for (const htmlFile of htmlFiles) {
+    await updateHtmlFile(htmlFile, oldBasePath, newBasePath)
+  }
+}
+
+const findHtmlFiles = async (dir: string): Promise<string[]> => {
+  return await TinyGlobby.glob('**/*.html', {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true,
+  })
+}
+
+const updateHtmlFile = async (filePath: string, oldBasePath: string, newBasePath: string): Promise<void> => {
+  const content = await Fs.read(filePath)
+
+  if (content === null) {
+    throw new Error(`Could not read HTML file: ${filePath}`)
+  }
+
+  // Simple regex-based approach to update base tag
+  // Look for existing base tag first
+  const baseTagRegex = /<base\s+href\s*=\s*["']([^"']*)["'][^>]*>/i
+
+  let updatedContent: string
+
+  if (baseTagRegex.test(content)) {
+    // Update existing base tag
+    updatedContent = content.replace(baseTagRegex, `<base href="${newBasePath}">`)
+  } else {
+    // Insert new base tag in head
+    const headRegex = /<head[^>]*>/i
+    const headMatch = content.match(headRegex)
+
+    if (headMatch) {
+      const insertPosition = headMatch.index! + headMatch[0].length
+      updatedContent = content.slice(0, insertPosition)
+        + `\n  <base href="${newBasePath}">`
+        + content.slice(insertPosition)
+    } else {
+      throw new Error(`Could not find <head> tag in HTML file: ${filePath}`)
+    }
+  }
+
+  await Fs.write({ path: filePath, content: updatedContent })
+}
+
+const updateManifest = async (buildPath: string, updates: Partial<PolenBuildManifest>): Promise<void> => {
+  const manifestPath = Path.join(buildPath, '.polen', 'build.json')
+  const manifestResult = await buildManifest.read(buildPath)
+  if (Err.is(manifestResult)) {
+    throw new Error(`Polen build manifest not found at: ${manifestPath}`)
+  }
+  const currentManifest = manifestResult
+
+  const updatedManifest = { ...currentManifest, ...updates }
+
+  await Fs.write({
+    path: manifestPath,
+    content: JSON.stringify(updatedManifest, null, 2),
+  })
+}

package/src/api/static/static.ts

@@ -0,0 +1,2 @@
+export * from './manifest.ts'
+export * from './rebase.ts'

package/src/api/utils/asset-url/asset-url.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { assetUrl, faviconUrl, joinPaths, pageUrl } from './asset-url.js'
+import { assetUrl, faviconUrl, joinPaths, pageUrl } from './asset-url.ts'
 
 describe('asset-url helpers', () => {
   describe('joinPaths', () => {
@@ -20,9 +20,9 @@ describe('asset-url helpers', () => {
 
   describe('assetUrl', () => {
     test('creates asset URLs with base path', () => {
-      expect(assetUrl('assets/app.js', '/')).toBe('/assets/app.js')
-      expect(assetUrl('assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
-      expect(assetUrl('/assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
+      expect(assetUrl('assets/app.ts', '/')).toBe('/assets/app.ts')
+      expect(assetUrl('assets/app.ts', '/my-app/')).toBe('/my-app/assets/app.ts')
+      expect(assetUrl('/assets/app.ts', '/my-app/')).toBe('/my-app/assets/app.ts')
     })
   })
 

package/src/api/vite/plugins/build.ts

@@ -1,7 +1,9 @@
 import type { Config } from '#api/config/index'
+import type { PolenBuildManifest } from '#api/static/manifest'
 import { Vite } from '#dep/vite/index'
 import { ViteVirtual } from '#lib/vite-virtual/index'
 import { Fs, Path } from '@wollybeard/kit'
+import packageJson from '../../../../package.json' with { type: 'json' }
 import { isKitUnusedExternalImport, isRadixModuleLevelDirective } from '../log-filters.ts'
 import { polenVirtual } from '../vi.ts'
 
@@ -10,7 +12,7 @@ export const Build = (config: Config.Config): Vite.Plugin[] => {
 
   // const outDir = Path.join(config.paths.project.rootDir, `dist`)
 
-  return [Manifest(config), {
+  return [Manifest(config), BuildManifest(config), {
     name: `polen:build-client`,
     apply: `build`,
     applyToEnvironment: Vite.isEnvironmentClient,
@@ -144,3 +146,25 @@ const Manifest = (config: Config.Config): Vite.Plugin => {
     ),
   }
 }
+
+const BuildManifest = (config: Config.Config): Vite.Plugin => {
+  return {
+    name: 'polen:build-manifest',
+    apply: 'build',
+    applyToEnvironment: Vite.isEnvironmentClient,
+    async generateBundle() {
+      const manifest: PolenBuildManifest = {
+        type: config.build.architecture === 'ssr' ? 'ssr' : 'ssg',
+        version: packageJson.version,
+        basePath: config.build.base || '/',
+      }
+
+      // Emit the manifest as an asset
+      this.emitFile({
+        type: 'asset',
+        fileName: '.polen/build.json',
+        source: JSON.stringify(manifest, null, 2),
+      })
+    },
+  }
+}

package/src/api/vite/plugins/core.ts

@@ -9,7 +9,7 @@ import { ViteVirtual } from '#lib/vite-virtual/index'
 import { debug } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import { Json, Str } from '@wollybeard/kit'
-import type { ProjectData } from '../../../project-data.js'
+import type { ProjectData } from '../../../project-data.ts'
 import { SchemaAugmentation } from '../../schema-augmentation/index.ts'
 import { Schema } from '../../schema/index.ts'
 import { createLogger } from '../logger.ts'