jax-hono 1.0.0

package/README.md

@@ -0,0 +1,17 @@
+# Jax-hono
+
+Jax 是本项目的轻量框架层。完整说明见 [docs/jax.md](docs/jax.md)。
+
+维护 Jax 内部代码时按目录职责放置文件：
+
+```txt
+core/       Hono runtime、生命周期、Controller/Service
+middleware/ 框架中间件
+plugins/    插件定义、内置插件配置、内置插件实现
+build/      代码生成/扫描注册
+helpers/    框架辅助函数
+utils/      纯工具函数
+errors/     统一错误类型
+types/      框架公共类型
+generated/  自动生成的注册表
+```

package/bin/jax.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+
+import { cac } from "cac";
+import { $ } from "bun";
+import path from "node:path";
+
+const cli = cac("jax");
+
+cli
+  .command(
+    "link",
+    "Create a symlink (./jax -> jax-hono installation directory)",
+  )
+  .action(async () => {
+    const sourceDir = path.resolve(import.meta.dir, "..");
+    const targetDir = path.resolve(process.cwd(), "jax");
+
+    if (process.platform === "win32") {
+      const result =
+        await $`cmd /c mklink /D ${targetDir} ${sourceDir}`.nothrow();
+      if (result.exitCode !== 0) {
+        console.error(
+          "Failed to create symlink. Make sure you run as Administrator.",
+        );
+        process.exit(1);
+      }
+      console.log(`Symlink created: ${targetDir} <<===>> ${sourceDir}`);
+    } else {
+      const relativeSource = path.relative(path.dirname(targetDir), sourceDir);
+      const result = await $`ln -sf ${relativeSource} ${targetDir}`.nothrow();
+      if (result.exitCode !== 0) {
+        console.error(`Failed to create symlink: ${result.stderr.toString()}`);
+        process.exit(1);
+      }
+      console.log(`Symlink created: ${targetDir} -> ${relativeSource}`);
+    }
+  });
+
+cli
+  .command("open", "Open jax-hono installation directory in file manager")
+  .action(async () => {
+    const sourceDir = path.resolve(import.meta.dir, "..");
+
+    let command: string[];
+    if (process.platform === "darwin") {
+      command = ["open", sourceDir];
+    } else if (process.platform === "win32") {
+      command = ["explorer", sourceDir];
+    } else {
+      command = ["xdg-open", sourceDir];
+    }
+
+    const [cmd, ...args] = command;
+    const result = await $`${cmd} ${args}`.nothrow();
+    if (result.exitCode !== 0) {
+      console.error(`Failed to open directory: ${result.stderr.toString()}`);
+      process.exit(1);
+    }
+    console.log(`Opened: ${sourceDir}`);
+  });
+
+cli.help();
+const parsed = cli.parse();
+
+// Show help when no command is matched (e.g. bare `jax` or unknown command)
+if (!cli.matchedCommand && !parsed.options.help) {
+  cli.outputHelp();
+}

package/build/build.ts

@@ -0,0 +1,19 @@
+import { setupJax } from '../setup'
+
+setupJax()
+
+const result = await Bun.build({
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  target: 'bun',
+})
+
+if (!result.success) {
+  for (const log of result.logs) {
+    console.error(log)
+  }
+
+  process.exit(1)
+}
+
+console.log('Build completed.')

package/build/generate-config.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, parse, relative } from 'node:path'
+
+const srcDir = join(import.meta.dir, '../..')
+const configDir = join(srcDir, 'config')
+const typesFile = join(srcDir, 'types/index.ts')
+const generatedDir = join(srcDir, 'jax/generated')
+const outputFile = join(generatedDir, 'config.ts')
+const envStages = new Set([
+  'default',
+  'local',
+  'dev',
+  'development',
+  'test',
+  'staging',
+  'pre',
+  'uat',
+  'prod',
+  'production',
+])
+
+function toImportName(fileName: string, index: number) {
+  return `config${index}_${parse(fileName).name.replace(/[^a-zA-Z0-9_$]/g, '_')}`
+}
+
+function getStage(fileName: string) {
+  const stage = parse(fileName).name.split('.').at(-1)
+
+  if (stage && envStages.has(stage)) {
+    return stage
+  }
+
+  return 'base'
+}
+
+function getImportPath(fileName: string) {
+  const { dir, name } = parse(fileName)
+  const path = join('../../config', dir, name).replaceAll('\\', '/')
+
+  return path.startsWith('.') ? path : `./${path}`
+}
+
+function getConfigFiles() {
+  if (!existsSync(configDir)) {
+    return []
+  }
+
+  return readdirSync(configDir)
+    .filter((fileName) => /^config\.[^.]+\.ts$/.test(fileName))
+    .sort((left, right) => {
+      const stageWeight: Record<string, number> = {
+        base: 0,
+        default: 1,
+      }
+
+      const diff = (stageWeight[getStage(left)] ?? 2) - (stageWeight[getStage(right)] ?? 2)
+
+      if (diff !== 0) {
+        return diff
+      }
+
+      return left.localeCompare(right)
+    })
+}
+
+function hasProjectConfigType() {
+  if (!existsSync(typesFile)) {
+    return false
+  }
+
+  const source = readFileSync(typesFile, 'utf8')
+
+  return /\bexport\s+(?:type|interface)\s+ProjectConfig\b/.test(source)
+}
+
+export function generateConfig() {
+  const files = getConfigFiles()
+  const defaultConfigIndex = files.findIndex((fileName) => getStage(fileName) === 'default')
+  const imports = files.map((fileName, index) => {
+    return `import ${toImportName(fileName, index)} from '${getImportPath(fileName)}'`
+  })
+  const modules = files.map((fileName, index) => {
+    return `  { name: '${fileName}', stage: '${getStage(fileName)}', config: ${toImportName(fileName, index)} },`
+  })
+  const hasProjectTypes = hasProjectConfigType()
+  const typeImports = hasProjectTypes ? [`import type { ProjectConfig } from '../../types'`] : []
+  const projectConfigType = hasProjectTypes
+    ? 'export type { ProjectConfig }'
+    : defaultConfigIndex === -1
+    ? 'export type ProjectConfig = Record<string, unknown>'
+    : `export type ProjectConfig = typeof ${toImportName(files[defaultConfigIndex], defaultConfigIndex)}`
+  const content = `${[...typeImports, ...imports].join('\n')}
+
+export const configModules = [
+${modules.join('\n')}
+] as const
+
+${projectConfigType}
+
+export default configModules
+`
+
+  mkdirSync(generatedDir, { recursive: true })
+
+  if (existsSync(outputFile) && readFileSync(outputFile, 'utf8') === content) {
+    return
+  }
+
+  writeFileSync(outputFile, content)
+  console.log(`Generated ${relative(srcDir, outputFile)} with ${files.length} config file(s).`)
+}
+
+if (import.meta.main) {
+  generateConfig()
+}