polen 0.10.0-next.19 → 0.10.0-next.21

package/src/api/config/merge.ts

@@ -1,4 +1,5 @@
 import { Vite } from '#dep/vite/index'
+import { spreadShallow } from '#lib/kit-temp'
 import type { ConfigInput } from './configurator.js'
 
 /**
@@ -13,40 +14,36 @@ export const mergeInputs = (
     return base
   }
 
-  const merged: ConfigInput = {
-    ...base,
-    ...overrides,
-  }
+  const merged: ConfigInput = spreadShallow(base, overrides)
 
   // Merge schema if both have it
-  if (base.schema || overrides.schema) {
+  if (base.schema ?? overrides.schema) {
     merged.schema = overrides.schema ?? base.schema
   }
 
   // Merge build config
-  if (base.build || overrides.build) {
-    merged.build = {
-      ...base.build,
-      ...overrides.build,
-    }
+  if (base.build ?? overrides.build) {
+    merged.build = spreadShallow(base.build, overrides.build)
+  }
+
+  // Merge server config
+  if (base.server ?? overrides.server) {
+    merged.server = spreadShallow(base.server, overrides.server)
   }
 
   // Merge advanced config
-  if (base.advanced || overrides.advanced) {
-    merged.advanced = {
-      ...base.advanced,
-      ...overrides.advanced,
-    }
+  if (base.advanced ?? overrides.advanced) {
+    merged.advanced = spreadShallow(base.advanced, overrides.advanced)
 
     // Merge advanced.watch config
-    if (base.advanced?.watch || overrides.advanced?.watch) {
-      merged.advanced.watch = {
-        ...base.advanced?.watch,
-        ...overrides.advanced?.watch,
-      }
+    if (base.advanced?.watch ?? overrides.advanced?.watch) {
+      merged.advanced.watch = spreadShallow(
+        base.advanced?.watch,
+        overrides.advanced?.watch,
+      )
 
       // Merge watch.also arrays
-      if (base.advanced?.watch?.also || overrides.advanced?.watch?.also) {
+      if (base.advanced?.watch?.also ?? overrides.advanced?.watch?.also) {
         merged.advanced.watch.also = [
           ...(base.advanced?.watch?.also ?? []),
           ...(overrides.advanced?.watch?.also ?? []),

package/src/api/content/scan.ts

@@ -73,7 +73,7 @@ export const scan = async (options: {
     // Update pages to have virtual root as parent if they don't have one
     const pagesWithVirtualRoot = pagesWithIds.map(page => ({
       ...page,
-      parentId: page.parentId || `__virtual_root__`,
+      parentId: page.parentId ?? `__virtual_root__`,
     }))
 
     tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])

package/src/api/content/sidebar.ts

@@ -173,13 +173,13 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
   }
 
   // Process top-level pages (direct children of the directory)
-  const topLevelPages = pagesByParent.get(topLevelDir) || []
+  const topLevelPages = pagesByParent.get(topLevelDir) ?? []
 
   // Sort pages by their directory order (extracted from file path)
   const sortedTopLevelPages = [...topLevelPages].sort((a, b) => {
     // For sections, we need to look at the directory name in the file path
-    const dirA = a.route.file.path.relative.dir.split(`/`).pop() || ``
-    const dirB = b.route.file.path.relative.dir.split(`/`).pop() || ``
+    const dirA = a.route.file.path.relative.dir.split(`/`).pop() ?? ``
+    const dirB = b.route.file.path.relative.dir.split(`/`).pop() ?? ``
 
     // Extract order from directory names like "10_b", "20_c"
     const orderMatchA = /^(\d+)[_-]/.exec(dirA)
@@ -197,7 +197,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
   for (const page of sortedTopLevelPages) {
     const pageName = page.route.logical.path[page.route.logical.path.length - 1]!
     const childPath = page.route.logical.path.join(`/`)
-    const childPages = pagesByParent.get(childPath) || []
+    const childPages = pagesByParent.get(childPath) ?? []
 
     if (childPages.length > 0 || FileRouter.routeIsFromIndexFile(page.route)) {
       // This is a section (has children or is an index page for a subdirectory)

package/src/api/project/index.ts

@@ -0,0 +1 @@
+export * from './validate.js'

package/src/api/project/validate.ts

@@ -0,0 +1,41 @@
+import { Fs } from '@wollybeard/kit'
+import consola from 'consola'
+
+export interface ValidateProjectOptions {
+  mustExist?: boolean
+  mustBeEmpty?: boolean
+  silent?: boolean
+}
+
+/**
+ * Validate a project directory for Polen operations.
+ * Used by CLI commands to ensure valid project paths.
+ */
+export async function validateProjectDirectory(
+  dir: string,
+  options: ValidateProjectOptions = {},
+): Promise<boolean> {
+  const { mustExist = true, mustBeEmpty = false, silent = false } = options
+
+  const stat = await Fs.stat(dir)
+
+  if (Fs.isNotFoundError(stat)) {
+    if (mustExist) {
+      if (!silent) consola.error(`Project directory does not exist: ${dir}`)
+      return false
+    }
+    return true
+  }
+
+  if (!stat.isDirectory()) {
+    if (!silent) consola.error(`Project path is not a directory: ${dir}`)
+    return false
+  }
+
+  if (mustBeEmpty && !(await Fs.isEmptyDir(dir))) {
+    if (!silent) consola.error(`Project directory is not empty: ${dir}`)
+    return false
+  }
+
+  return true
+}

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

@@ -162,7 +162,7 @@ const BuildManifest = (config: Config.Config): Vite.Plugin => {
       const manifest: PolenBuildManifest = {
         type: config.build.architecture === `ssr` ? `ssr` : `ssg`,
         version: packageJson.version,
-        basePath: config.build.base || `/`,
+        basePath: config.build.base ?? `/`,
       }
 
       // Emit the manifest as an asset

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

@@ -209,6 +209,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
               paths: config.paths.project,
               navbar, // Complete navbar with schema and pages
               server: {
+                port: config.server.port,
                 static: {
                   // todo
                   // relative from CWD of process that boots n1ode server

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

@@ -99,7 +99,7 @@ export const Serve = (
     config() {
       return {
         server: {
-          port: 3000,
+          port: config.server.port,
           watch: {
             disableGlobbing: false,
           },

package/src/cli/_/parameters.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+/**
+ * Common parameter schemas for CLI commands
+ */
+
+export const projectParameter = z
+  .string()
+  .optional()
+  .describe(`The path to the project directory. Default is CWD (current working directory).`)

package/src/cli/commands/build.ts

@@ -1,11 +1,16 @@
 // @ts-nocheck
 import { Api } from '#api/index'
-import { Vite } from '#dep/vite/index'
+import { projectParameter } from '#cli/_/parameters'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
 import { Command } from '@molt/command'
 import { z } from 'zod'
 
 const args = Command.create()
   .parameter(`--debug -d`, z.boolean().default(false))
+  .parameter(
+    `--project -p`,
+    projectParameter,
+  )
   .parameter(
     `--architecture -a`,
     Api.Config.BuildArchitecture.default('ssg').describe('Which kind of application architecture to output.'),
@@ -14,6 +19,10 @@ const args = Command.create()
     `--base -b`,
     z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
   )
+  .parameter(
+    `--port`,
+    z.number().optional().describe('Default port for the SSR application'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -27,14 +36,20 @@ const args = Command.create()
   })
   .parse()
 
-// HACK:
-// todo
-// we don't want to  lose pretty preting of defaults in Molt but
-// we don't want cli defaults to override explicit inputs in the config file either
-// we need something like setset and/or an ability in molt to show a default but then have undefined internally etc.
-// and now if user passes --no-debug/ --debug false it has no effect which is wrong since its not via default anymore, ... ugh
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
+
 await Api.Builder.build({
-  ...(args.debug === false ? {} : { debug: args.debug }),
-  ...(args.architecture === 'ssg' ? {} : { architecture: args.architecture }),
-  ...(args.base ? { base: args.base } : {}),
+  dir,
+  architecture: args.architecture,
+  base: args.base,
+  server: {
+    port: args.port,
+  },
+  advanced: {
+    debug: args.debug,
+  },
 })

package/src/cli/commands/config/create.ts

@@ -1,6 +1,23 @@
+import { Api } from '#api/index'
+import { projectParameter } from '#cli/_/parameters'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
+import { Command } from '@molt/command'
 import { Fs, Path } from '@wollybeard/kit'
 import consola from 'consola'
 
+const args = Command.create()
+  .parameter(
+    `--project -p`,
+    projectParameter,
+  )
+  .parse()
+
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
+
 const fileName = 'polen.config.ts'
 const fileContent = `import { Polen } from 'polen'
 
@@ -9,7 +26,7 @@ export default Polen.defineConfig({
 })
 `
 
-const filePath = Path.join(process.cwd(), fileName)
+const filePath = Path.join(dir, fileName)
 
 const exists = await Fs.exists(filePath)
 if (exists) {

package/src/cli/commands/create.ts

@@ -1,4 +1,5 @@
 // @ts-nocheck
+import { Api } from '#api/index'
 import { Command } from '@molt/command'
 import { Err, Fs, Manifest, Name, Path, Str } from '@wollybeard/kit'
 import * as Ansis from 'ansis'
@@ -48,10 +49,9 @@ const args = Command
 
 const getProjectRoot = async (): Promise<string> => {
   if (args.path) {
-    const stat = await Fs.stat(args.path)
-    if (Fs.isNotFoundError(stat)) return args.path
-    if (stat.isDirectory() && await Fs.isEmptyDir(args.path)) return args.path
-    consola.error(`The given path ${args.path} already exists and is not an empty directory`)
+    if (await Api.Project.validateProjectDirectory(args.path, { mustExist: false, mustBeEmpty: true })) {
+      return args.path
+    }
     process.exit(1)
   }
 

package/src/cli/commands/dev.ts

@@ -1,9 +1,10 @@
 // @ts-nocheck
 import { Api } from '#api/index'
+import { projectParameter } from '#cli/_/parameters'
 import { Vite } from '#dep/vite/index'
-import { ensureOptionalAbsolute, ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
 import { Command } from '@molt/command'
-import { Err, Path } from '@wollybeard/kit'
+import { Err } from '@wollybeard/kit'
 import { z } from 'zod'
 
 const args = Command.create()
@@ -11,12 +12,16 @@ const args = Command.create()
   .parameter(
     `--project -p`,
     // @ts-expect-error
-    z.string().optional().describe(`The path to the project directory. Default is CWD (current working directory).`),
+    projectParameter,
   )
   .parameter(
     `--base -b`,
     z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
   )
+  .parameter(
+    `--port`,
+    z.number().optional().describe('Port to run the development server on'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -30,12 +35,21 @@ const args = Command.create()
   })
   .parse()
 
-const dir = ensureOptionalAbsoluteWithCwd(args.project) as string
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
 
 const viteUserConfig = await Api.ConfigResolver.fromFile({
   dir,
   overrides: {
-    ...(args.base ? { build: { base: args.base } } : {}),
+    build: {
+      base: args.base,
+    },
+    server: {
+      port: args.port,
+    },
     advanced: {
       debug: args.debug,
     },

package/src/lib/graphql-document/components/GraphQLDocument.tsx

@@ -202,13 +202,15 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
         data-testid='graphql-document'
       >
         {/* Base code block */}
-        {renderCode ? (
-          renderCode()
-        ) : (
-          <pre className='code-block'>
+        {renderCode
+          ? (
+            renderCode()
+          )
+          : (
+            <pre className='code-block'>
             <code>{children}</code>
-          </pre>
-        )}
+            </pre>
+          )}
 
         {/* Interactive overlay layer */}
         {!plain && isReady && (

package/src/lib/kit-temp.test.ts

@@ -1,6 +1,6 @@
 import * as fc from 'fast-check'
 import { describe, expect, test } from 'vitest'
-import { objFilter, ObjOmit, ObjPick, objPolicyFilter } from './kit-temp.js'
+import { objFilter, ObjOmit, ObjPick, objPolicyFilter, spreadShallow } from './kit-temp.js'
 
 describe('objPolicyFilter', () => {
   const testObj = { a: 1, b: 2, c: 3, d: 4 }
@@ -137,3 +137,87 @@ describe('property-based tests', () => {
     )
   })
 })
+
+describe('mergeShallow', () => {
+  test('merges objects while omitting undefined values', () => {
+    const base = { a: 1, b: 2, c: 3 }
+    const override = { b: undefined, c: 4, d: 5 }
+
+    expect(spreadShallow(base, override)).toEqual({ a: 1, b: 2, c: 4, d: 5 })
+  })
+
+  test('handles multiple objects', () => {
+    const obj1 = { a: 1, b: 2 }
+    const obj2 = { b: undefined, c: 3 }
+    const obj3 = { c: undefined, d: 4 }
+
+    expect(spreadShallow(obj1, obj2, obj3)).toEqual({ a: 1, b: 2, c: 3, d: 4 })
+  })
+
+  test('handles empty objects', () => {
+    expect(spreadShallow({}, {})).toEqual({})
+    expect(spreadShallow({ a: 1 }, {})).toEqual({ a: 1 })
+    expect(spreadShallow({}, { a: 1 })).toEqual({ a: 1 })
+  })
+
+  test('handles single object', () => {
+    const obj = { a: 1, b: undefined, c: 3 }
+    expect(spreadShallow(obj)).toEqual({ a: 1, c: 3 })
+  })
+
+  test('handles no objects', () => {
+    expect(spreadShallow()).toEqual({})
+  })
+
+  test('handles undefined objects', () => {
+    const obj = { a: 1, b: 2 }
+    expect(spreadShallow(undefined, obj, undefined)).toEqual({ a: 1, b: 2 })
+    expect(spreadShallow(obj, undefined)).toEqual({ a: 1, b: 2 })
+    expect(spreadShallow(undefined, undefined)).toEqual({})
+  })
+
+  test('preserves null values', () => {
+    const obj1 = { a: 1, b: null }
+    const obj2 = { b: 2, c: null }
+    expect(spreadShallow(obj1, obj2)).toEqual({ a: 1, b: 2, c: null })
+  })
+
+  test('preserves false and 0 values', () => {
+    const obj1 = { a: true, b: 1 }
+    const obj2 = { a: false, b: 0 }
+    expect(spreadShallow(obj1, obj2)).toEqual({ a: false, b: 0 })
+  })
+
+  test('property-based: never includes undefined values', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.object({ withUndefined: true })),
+        (objects) => {
+          const result = spreadShallow(...objects)
+          Object.values(result).forEach(value => {
+            expect(value).not.toBe(undefined)
+          })
+        },
+      ),
+    )
+  })
+
+  test('property-based: later objects override earlier ones', () => {
+    fc.assert(
+      fc.property(
+        fc.object(),
+        fc.object(),
+        fc.string(),
+        fc.anything({ withUndefined: false }),
+        (obj1, obj2, key, value) => {
+          // Set the same key in both objects
+          obj1[key] = 'first'
+          obj2[key] = value
+
+          const result = spreadShallow(obj1, obj2)
+          expect(result[key]).toBe(value)
+        },
+      ),
+    )
+  })
+})

package/src/lib/kit-temp.ts

@@ -592,3 +592,54 @@ export const brand = <$BaseType, $BrandName extends string>(
 ): Brand<$BaseType, $BrandName> => {
   return value as Brand<$BaseType, $BrandName>
 }
+
+/**
+ * Shallow merge objects while omitting undefined values.
+ *
+ * This utility simplifies the common pattern of conditionally spreading objects
+ * to avoid including undefined values that would override existing values.
+ *
+ * @param objects - Objects to merge (later objects override earlier ones). Undefined objects are ignored.
+ * @returns Merged object with undefined values omitted
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * const overrides = {
+ *   ...(value1 ? { key1: value1 } : {}),
+ *   ...(value2 ? { key2: value2 } : {}),
+ * }
+ *
+ * // Use:
+ * const overrides = mergeShallow({
+ *   key1: value1,
+ *   key2: value2,
+ * })
+ *
+ * // Example with config merging:
+ * const config = mergeShallow(
+ *   defaultConfig,
+ *   userConfig,
+ *   { debug: args.debug, base: args.base }
+ * )
+ * // undefined values in the last object won't override earlier values
+ * ```
+ */
+export const spreadShallow = <T extends object>(...objects: (T | undefined)[]): T => {
+  const result = {} as T
+
+  for (const obj of objects) {
+    if (obj === undefined) continue
+
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        const value = obj[key]
+        if (value !== undefined) {
+          result[key] = value
+        }
+      }
+    }
+  }
+
+  return result
+}

package/src/lib/react-router-aid/get-paths-patterns.ts

@@ -41,7 +41,7 @@ export const _getPathsRecurse = (
     if (isIndexRoute(route)) {
       // Index route uses the parent's accumulated path.
       // If parentPath is empty (implying root), it should be ROOT_PATH
-      collectedPaths.add(parentPath || ROOT_PATH)
+      collectedPaths.add(parentPath ?? ROOT_PATH)
 
       continue
     }

package/src/project-data.ts

@@ -8,6 +8,7 @@ export interface ProjectData {
   paths: Config.Config[`paths`][`project`]
   navbar: NavbarItem[]
   server: {
+    port: number
     static: {
       directory: string
       route: string

package/src/template/server/main.ts

@@ -1,5 +1,6 @@
 import { serve } from '@hono/node-server' // TODO: support non-node platforms.
 import { neverCase } from '@wollybeard/kit/language'
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { createApp } from './app.js'
 import { generate } from './ssg/generate.js'
 import { view } from './view.js'
@@ -10,7 +11,7 @@ if (__BUILDING__) {
       await generate(view)
       break
     case `ssr`:
-      const port = process.env[`PORT`] ? parseInt(process.env[`PORT`]) : 3001 // todo viteConfigResolved.server.port + 1
+      const port = process.env[`PORT`] ? parseInt(process.env[`PORT`]) : PROJECT_DATA.server.port
       const app = createApp()
       serve({ fetch: app.fetch, port })
       break