@wular/pnext 0.0.24 → 0.1.0

package/src/cli/index.ts

@@ -1,14 +1,26 @@
 #!/usr/bin/env bun
-import { existsSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
+import { bold, cyan, dim } from '../utils/ansi'
 import { markBoot } from './boot/trace'
 import { commandBinaryName, nameEsbuildProcess, namedBunBinary } from './boot/named-bin'
 
-const MIN_BUN = '1.3.6'
+const MIN_BUN = '1.3.10'
 // Not a floor but a hole in one: 1.3.14 segfaults about a second into serving,
 // so a pnext server dies before its first response with no error of its own to
 // show. 1.3.13 and 1.4.x are both fine.
 const BROKEN_BUN = new Set(['1.3.14'])
+const VERSION = packageVersion()
+const COMMANDS = new Set([
+  'dev',
+  'build',
+  'start',
+  'analyze',
+  'typegen',
+  'create',
+  'migrate',
+  'info',
+])
 
 // Reached only if something bypassed bin/pnext (which guards the same way).
 if (typeof Bun === 'undefined') {
@@ -43,7 +55,14 @@ nameEsbuildProcess()
 markBoot('cli:naming')
 
 try {
-  if (command === 'dev') {
+  if (command === '--version' || command === '-v') {
+    console.log(VERSION)
+  } else if (command === '--help' || command === '-h' || !command) {
+    printHelp()
+  } else if (COMMANDS.has(command) && (args.includes('--help') || args.includes('-h'))) {
+    printCommandHelp(command)
+  } else if (command === 'dev') {
+    warnUnknownFlags(command, args)
     const { dev } = await import('./dev')
     await dev({
       root: positionalRoot(args),
@@ -51,6 +70,7 @@ try {
       hostname: optionString(args, '--hostname'),
     })
   } else if (command === 'build') {
+    warnUnknownFlags(command, args)
     const { buildProject } = await import('./build')
     await buildProject(positionalRoot(args), {
       adapter: adapterOption(args),
@@ -68,6 +88,7 @@ try {
     // terminates once buildProject resolves.
     process.exit(0)
   } else if (command === 'start') {
+    warnUnknownFlags(command, args)
     const root = positionalRoot(args)
     // The build emits src/cli/start.ts prebundled into one file; parsing that
     // instead of walking the framework's source graph is most of `start`'s
@@ -83,6 +104,7 @@ try {
       hostname: optionString(args, '--hostname'),
     })
   } else if (command === 'analyze') {
+    warnUnknownFlags(command, args)
     const { analyzeProject } = await import('./analyze')
     const { route, root } = analyzePositionals(args)
     const result = await analyzeProject(root, {
@@ -96,6 +118,7 @@ try {
       printAnalyzeResult(result, { route, files: args.includes('--files') })
     }
   } else if (command === 'typegen') {
+    warnUnknownFlags(command, args)
     const { typegenProject } = await import('./typegen')
     const result = await typegenProject(positionalRoot(args))
     console.log(
@@ -105,13 +128,18 @@ try {
     // handles (timers/connections) alive — a one-shot command must not hang.
     process.exit(0)
   } else if (command === 'create') {
+    warnUnknownFlags(command, args)
     const { createApp } = await import('./create')
     await createApp(positionals(args)[0], { install: !args.includes('--no-install') })
     process.exit(0)
   } else if (command === 'migrate') {
+    warnUnknownFlags(command, args)
     const { migrateApp } = await import('./migrate/run')
     const code = await migrateApp(positionalRoot(args), { dryRun: args.includes('--dry-run') })
     process.exit(code)
+  } else if (command === 'info') {
+    warnUnknownFlags(command, args)
+    printInfo()
   } else {
     printHelp()
     process.exit(command ? 1 : 0)
@@ -238,12 +266,120 @@ function analyzeCompression(args: string[]) {
   return args.includes('--brotli') ? 'brotli' : 'gzip'
 }
 
+function packageVersion() {
+  const packageJson = JSON.parse(
+    readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+  ) as {
+    version?: unknown
+  }
+  return typeof packageJson.version === 'string' ? packageJson.version : 'unknown'
+}
+
+function warnUnknownFlags(command: string, args: string[]) {
+  const flags = commandFlags(command)
+  for (const arg of args) {
+    if (!arg.startsWith('-') || arg === '--') continue
+    const name = arg.startsWith('--') ? arg.split('=', 1)[0]! : arg
+    if (!flags.has(name)) console.warn(`Warning: unknown option '${name}' was ignored.`)
+  }
+}
+
+function commandFlags(command: string) {
+  const flags = new Set(['--help', '-h'])
+  if (command === 'dev' || command === 'start') {
+    flags.add('--port')
+    flags.add('--hostname')
+  }
+  if (command === 'build') {
+    for (const flag of [
+      '--adapter',
+      '--verbose',
+      '--experimental-build-mode',
+      '--debug-build-paths',
+      '--debug-prerender',
+    ])
+      flags.add(flag)
+  }
+  if (command === 'analyze') for (const flag of ['--json', '--files', '--brotli']) flags.add(flag)
+  if (command === 'create') flags.add('--no-install')
+  if (command === 'migrate') flags.add('--dry-run')
+  return flags
+}
+
+function printInfo() {
+  const config = configPresence(process.cwd())
+  console.log(`pnext info
+  pnext: ${VERSION}
+  bun: ${Bun.version}
+  os: ${process.platform} ${process.arch}
+  package manager: ${packageManager(process.cwd())}
+  pnext.config: ${config.pnext}
+  next.config: ${config.next}`)
+}
+
+function packageManager(root: string) {
+  if (existsSync(path.join(root, 'bun.lock')) || existsSync(path.join(root, 'bun.lockb')))
+    return 'bun'
+  if (existsSync(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(path.join(root, 'yarn.lock'))) return 'yarn'
+  if (existsSync(path.join(root, 'package-lock.json'))) return 'npm'
+  return 'unknown'
+}
+
+function configPresence(root: string) {
+  const find = (base: string) => {
+    const file = ['js', 'mjs', 'cjs', 'ts']
+      .map(extension => `${base}.${extension}`)
+      .find(file => existsSync(path.join(root, file)))
+    return file ?? 'none'
+  }
+  return { pnext: find('pnext.config'), next: find('next.config') }
+}
+
 function printHelp() {
-  console.log(`pnext dev [directory] [--port 3000] [--hostname 127.0.0.1]
-pnext build [directory] [--adapter vercel] [--verbose]
-pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
-pnext analyze [route] [directory] [--brotli] [--files] [--json]
-pnext typegen [directory]
-pnext create <directory> [--no-install]
-pnext migrate [directory] [--dry-run]`)
+  const commands: [string, string][] = [
+    ['dev', 'Start the development server.'],
+    ['build', 'Create a production build.'],
+    ['start', 'Start the production server.'],
+    ['analyze', 'Analyze production bundle output.'],
+    ['typegen', 'Generate route TypeScript definitions.'],
+    ['create', 'Create a new pnext application.'],
+    ['migrate', 'Migrate a Next.js application to pnext.'],
+    ['info', 'Print environment details for bug reports.'],
+  ]
+  const flags: [string, string][] = [
+    ['--port <port>', 'Port to listen on (default: 3000).'],
+    ['--hostname <hostname>', 'Hostname to listen on (default: 0.0.0.0).'],
+    ['--version, -v', 'Print the pnext version.'],
+    ['--help, -h', 'Show this help message.'],
+  ]
+  const row = ([name, text]: [string, string], width: number) =>
+    `  ${cyan(name.padEnd(width))} ${dim(text)}`
+  console.log(`⚡ ${bold('pnext')} ${dim(VERSION)}
+
+${bold('Usage:')} pnext ${cyan('<command>')} [options]
+
+${bold('Commands:')}
+${commands.map(entry => row(entry, 9)).join('\n')}
+
+${bold('Common flags:')}
+${flags.map(entry => row(entry, 21)).join('\n')}
+
+${bold('Docs:')} ${cyan('https://pnext.dev')}`)
+}
+
+function printCommandHelp(command: string) {
+  const help: Record<string, string> = {
+    dev: `Usage: pnext dev [directory] [options]\n\nFlags:\n  --port <port>          Port to listen on (default: 3000).\n  --hostname <hostname>  Hostname to listen on (default: 0.0.0.0).`,
+    build: `Usage: pnext build [directory] [options]\n\nFlags:\n  --adapter <adapter>                  Deployment adapter (vercel).\n  --verbose                            Print detailed build output.\n  --experimental-build-mode <mode>     Build mode: compile or generate.\n  --debug-build-paths <patterns>       Build matching routes only.\n  --debug-prerender                    Debug prerender failures.`,
+    start: `Usage: pnext start [directory] [options]\n\nFlags:\n  --port <port>          Port to listen on (default: 3000).\n  --hostname <hostname>  Hostname to listen on (default: 0.0.0.0).`,
+    analyze: `Usage: pnext analyze [route] [directory] [options]\n\nFlags:\n  --json                 Print JSON output.\n  --files                Include individual files.\n  --brotli               Report Brotli compression.`,
+    typegen: 'Usage: pnext typegen [directory]',
+    create:
+      'Usage: pnext create <directory> [options]\n\nFlags:\n  --no-install           Skip dependency installation.',
+    migrate:
+      'Usage: pnext migrate [directory] [options]\n\nFlags:\n  --dry-run              Preview changes without writing.',
+    info: 'Usage: pnext info',
+  }
+  console.log(help[command])
 }

package/src/cli/migrate/report.ts

@@ -37,7 +37,7 @@ export function emptyResult(): MigrationResult {
 
 export function printHeader(root: string, dryRun: boolean) {
   const suffix = dryRun ? 'dry run, nothing will be written' : root
-  console.log(`\n${cyan('▲')} ${bold('pnext migrate')} ${dim(`— ${suffix}`)}`)
+  console.log(`\n⚡ ${bold('pnext migrate')} ${dim(`— ${suffix}`)}`)
 }
 
 export function printResult(result: MigrationResult, options: { install: string }) {

package/src/cli/serve/pipeline.ts

@@ -254,6 +254,24 @@ export async function createRequestHandler(
   })
 
   async function renderNotFound(request: Request): Promise<Response> {
+    const built = await maybeBuiltFile(
+      config.outPath,
+      '/404',
+      manifest.staticFiles,
+      request.method,
+      request.headers,
+      nextCompat,
+    )
+    if (built) {
+      setWorkUnitRoute('html', 'static')
+      const headers = new Headers(built.headers)
+      headers.set('x-nextjs-cache', 'HIT')
+      if (!hasBuildCapturedCacheControl(manifest.staticFiles?.['404.html'])) {
+        headers.delete('cache-control')
+      }
+      headers.delete('content-length')
+      return compressResponse(new Response(built.body, { status: 404, headers }), request)
+    }
     return compressResponse(
       await renderGlobalNotFoundResponse({
         config,
@@ -514,12 +532,7 @@ export async function createRequestHandler(
         // which owns the one rule (Next's static / ISR / dynamic values) for
         // rendered and prebuilt pages alike. maybeBuiltFile's `no-cache` is its
         // asset default, not a claim; a build-captured header is a claim and stays.
-        if (
-          isHtmlResponse(staticFile) &&
-          !(servedBuilt.metadata?.headers ?? []).some(
-            ([key]) => key.toLowerCase() === 'cache-control',
-          )
-        ) {
+        if (isHtmlResponse(staticFile) && !hasBuildCapturedCacheControl(servedBuilt.metadata)) {
           staticFile.headers.delete('cache-control')
         }
         if (servedBuilt.metadata) {
@@ -1035,6 +1048,10 @@ interface BuiltFileInfo {
   metadata?: StaticFileMetadata
 }
 
+function hasBuildCapturedCacheControl(metadata: StaticFileMetadata | undefined): boolean {
+  return (metadata?.headers ?? []).some(([key]) => key.toLowerCase() === 'cache-control')
+}
+
 // The prebuilt output file a GET for `pathname` would serve (page html or a
 // static route-handler body), plus its ISR metadata from the build manifest.
 async function builtFileInfo(

package/src/cli/serve/ui.ts

@@ -40,7 +40,7 @@ export function printServerReady({ mode, hostname, port, elapsedMs }: ReadyBanne
 
   const pad = Math.max(...rows.map(([label]) => label.length))
   console.log('')
-  console.log(`${cyan('▲')} ${bold('pnext')} ${dim(mode)}`)
+  console.log(`⚡ ${bold('pnext')} ${dim(mode)}`)
   for (const [label, value] of rows) {
     console.log(`  ${dim('-')} ${dim(label.padEnd(pad))}  ${value}`)
   }

package/src/cli/start.ts

@@ -47,7 +47,8 @@ export async function maybeBuiltFile(
 export async function start(options: StartOptions = {}) {
   const startedAt = Date.now()
   const port = options.port ?? 3000
-  const hostname = options.hostname ?? 'localhost'
+  // Next's documented default. Bun resolves 'localhost' to ::1 only, refusing IPv4 clients.
+  const hostname = options.hostname ?? '0.0.0.0'
   // Export builds are not served; pnext serves its standalone output directly.
   const config = await guardUnservableOutputMode(options.root)
   const manifest = await readProductionManifest(config)

package/src/cli/typegen.ts

@@ -64,14 +64,17 @@ async function writeChecks(config: ResolvedConfig, routes: RouteManifestEntry[])
   await rm(checksDir, { recursive: true, force: true })
   await ensureDir(checksDir)
 
+  // Metadata code routes (sitemap.ts, opengraph-image.tsx, ...) keep their
+  // Next-style signatures, which are not PNextRouteHandlerModule shapes.
+  const checked = routes.filter(route => !route.metadataRoute)
   await Promise.all(
-    routes.map(route => {
+    checked.map(route => {
       const file = path.join(checksDir, `${route.id}.check.ts`)
       return writeIfChanged(file, checkSource(checksDir, route))
     }),
   )
 
-  return routes.length
+  return checked.length
 }
 
 async function writeRouteAliases(config: ResolvedConfig, routes: RouteManifestEntry[]) {