jax-hono 1.0.14 → 1.0.16

package/README.md

@@ -1,6 +1,8 @@
 # Jax-hono
 
-Jax 是本项目的轻量框架层。完整说明见 [docs/jax.md](docs/jax.md)。
+Jax 是本项目的轻量框架层。完整说明见 [docs/jax.md](docs/jax.md)。
+
+给 Codex、Claude 等代码代理看的维护说明见 [docs/agent.md](docs/agent.md)。
 
 维护 Jax 内部代码时按目录职责放置文件：
 

package/build/generate-registry.ts

@@ -1,10 +1,12 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { cwd } from 'node:process'
-import { basename, join, parse, relative } from 'node:path'
-import { ensureGeneratedDir, generatedDir, packageDir, projectDir } from './generated-path'
-
-const srcDir = join(cwd(), 'src')
-const moduleExtensions = new Set(['.ts', '.js', '.mjs', '.cjs'])
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { cwd } from 'node:process'
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
+import { ensureGeneratedDir, generatedDir, packageDir, projectDir } from './generated-path'
+
+const srcDir = join(cwd(), 'src')
+const projectRequire = createRequire(join(projectDir, 'package.json'))
+const moduleExtensions = new Set(['.ts', '.js', '.mjs', '.cjs'])
 const generatedHeader = `// This file is generated by jax-hono/build/generate-registry.ts.
 // Do not edit it directly.
 `
@@ -23,14 +25,20 @@ type PluginConfigItem =
       options?: unknown
     }
 
-type PluginConfig = Record<string, PluginConfigItem>
+type PluginConfig = Record<string, PluginConfigItem>
+
+type EnabledPlugin = {
+  name: string
+  packageName: string
+  rootDir: string
+}
 
 const controllerGroups: ControllerGroup[] = [
   { name: 'api', dirs: ['api', 'controllers/api', 'controller/api', 'modules'], suffix: '.api' },
   { name: 'backend', dirs: ['backend', 'controllers/backend', 'controller/backend', 'modules'], suffix: '.backend' },
   { name: 'open', dirs: ['open', 'controllers/open', 'controller/open', 'modules'], suffix: '.open' },
   { name: 'client', dirs: ['client', 'controllers/client', 'controller/client', 'modules'], suffix: '.client' },
-  { name: 'controller', dirs: ['controllers', 'controller'] },
+  { name: 'controller', dirs: ['controllers', 'controller', 'modules'], suffix: '.controller' },
 ]
 
 const scopedControllerGroups = new Set(
@@ -126,18 +134,28 @@ function stripKnownSuffix(modulePath: string, suffixes: string[]) {
   return modulePath
 }
 
-function normalizeModulePath(modulePath: string) {
-  const parts = modulePath.split('/')
-  const last = parts.at(-1)
-  const parent = parts.at(-2)
-
-  return last && parent && last === parent
-    ? parts.slice(0, -1).join('/')
-    : modulePath
-}
-
-function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []) {
-  const modulePath = relative(join(srcDir, baseDir), filePath)
+function normalizeModulePath(modulePath: string) {
+  const parts = modulePath.split('/')
+  const last = parts.at(-1)
+  const parent = parts.at(-2)
+
+  if (!last || !parent) {
+    return modulePath
+  }
+
+  if (last === parent) {
+    return parts.slice(0, -1).join('/')
+  }
+
+  if (last.startsWith(`${parent}-`) || last.startsWith(`${parent}_`)) {
+    return [...parts.slice(0, -2), last].join('/')
+  }
+
+  return modulePath
+}
+
+function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []) {
+  const modulePath = relative(join(srcDir, baseDir), filePath)
     .replace(parse(filePath).ext, '')
     .replaceAll('\\', '/')
   const withoutIndex = modulePath.endsWith('/index')
@@ -146,16 +164,36 @@ function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []
 
   const stripped = stripKnownSuffix(withoutIndex, suffixes)
 
-  return baseDir === 'modules' ? normalizeModulePath(stripped) : stripped
-}
+  return baseDir === 'modules' ? normalizeModulePath(stripped) : stripped
+}
+
+function toPluginModulePath(pluginName: string, rootDir: string, filePath: string, suffixes: string[] = []) {
+  const modulePath = relative(rootDir, filePath)
+    .replace(parse(filePath).ext, '')
+    .replaceAll('\\', '/')
+  const withoutIndex = modulePath.endsWith('/index')
+    ? modulePath.slice(0, -'/index'.length)
+    : modulePath
+  const stripped = stripKnownSuffix(withoutIndex, suffixes)
+
+  return normalizeModulePath(stripped ? `${pluginName}/${stripped}` : pluginName)
+}
 
 function uniqueSorted(values: string[]) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right))
 }
 
-function getFilesFromDirs(dirs: string[]) {
-  return uniqueSorted(dirs.flatMap((dirName) => walkFiles(join(srcDir, dirName))))
-}
+function getFilesFromDirs(dirs: string[]) {
+  return uniqueSorted(dirs.flatMap((dirName) => walkFiles(join(srcDir, dirName))))
+}
+
+function getEnabledPluginFiles(suffix: string) {
+  return getEnabledPlugins().flatMap((plugin) => {
+    return walkFiles(plugin.rootDir)
+      .filter((filePath) => isSuffixedModuleFile(filePath, suffix))
+      .map((filePath) => ({ ...plugin, filePath }))
+  })
+}
 
 function isFileInDir(filePath: string, dirName: string) {
   const rel = relative(join(srcDir, dirName), filePath)
@@ -170,13 +208,13 @@ function isSuffixedModuleFile(filePath: string, suffix: string) {
     .endsWith(suffix)
 }
 
-function isModuleFeatureFile(filePath: string, suffix: string) {
-  return !isFileInDir(filePath, 'modules') || isSuffixedModuleFile(filePath, suffix)
-}
-
-function hasDefaultExport(filePath: string) {
-  return /\bexport\s+default\b/.test(readFileSync(filePath, 'utf8'))
-}
+function isModuleFeatureFile(filePath: string, suffix: string) {
+  return !isFileInDir(filePath, 'modules') || isSuffixedModuleFile(filePath, suffix)
+}
+
+function hasDefaultExport(filePath: string) {
+  return /\bexport\s+default\b/.test(readFileSync(filePath, 'utf8'))
+}
 
 function indentObject(content: string, spaces = 2) {
   if (!content) {
@@ -221,27 +259,39 @@ function buildNestedObject(entries: { path: string[]; value: string }[]): string
 }
 
 function generateControllersRegistry() {
-  const used = new Set<string>()
-  const imports: string[] = []
-  const groupLines: string[] = []
-
-  for (const group of controllerGroups) {
-    const entries = getFilesFromDirs(group.dirs)
-      .filter((filePath) => basename(filePath) !== 'index.ts')
-      .filter((filePath) => !group.suffix || isModuleFeatureFile(filePath, group.suffix))
-      .filter(hasDefaultExport)
-      .map((filePath, index) => {
-        const baseDir = group.dirs.find((dirName) => {
-          return isFileInDir(filePath, dirName)
-        }) ?? group.dirs[0]
-        const modulePath = toModulePath(baseDir, filePath, group.suffix ? [group.suffix] : [])
-        const importName = toIdentifier([group.name, modulePath, String(index), 'Controller'])
-
-        return { modulePath, importName, filePath }
-      })
-      .filter((entry) => {
-        if (group.name !== 'controller') {
-          return true
+  const used = new Set<string>()
+  const imports: string[] = []
+  const groupLines: string[] = []
+
+  for (const group of controllerGroups) {
+    const projectEntries = getFilesFromDirs(group.dirs)
+      .filter((filePath) => basename(filePath) !== 'index.ts')
+      .filter((filePath) => !group.suffix || isModuleFeatureFile(filePath, group.suffix))
+      .filter(hasDefaultExport)
+      .map((filePath, index) => {
+        const baseDir = group.dirs.find((dirName) => {
+          return isFileInDir(filePath, dirName)
+        }) ?? group.dirs[0]
+        const modulePath = toModulePath(baseDir, filePath, group.suffix ? [group.suffix] : [])
+        const importName = toIdentifier([group.name, modulePath, String(index), 'Controller'])
+
+        return { modulePath, importName, filePath }
+      })
+    const pluginEntries = group.name === 'controller'
+      ? getEnabledPluginFiles('.controller')
+        .filter(({ filePath }) => basename(filePath) !== 'index.ts')
+        .filter(({ filePath }) => hasDefaultExport(filePath))
+        .map(({ name, rootDir, filePath }, index) => {
+          const modulePath = toPluginModulePath(name, rootDir, filePath, ['.controller'])
+          const importName = toIdentifier([group.name, 'plugin', modulePath, String(index), 'Controller'])
+
+          return { modulePath, importName, filePath }
+        })
+      : []
+    const entries = [...projectEntries, ...pluginEntries]
+      .filter((entry) => {
+        if (group.name !== 'controller') {
+          return true
         }
 
         const [scope] = entry.modulePath.split('/')
@@ -266,16 +316,17 @@ function generateControllersRegistry() {
       continue
     }
 
-    const objectBody = indentObject(
-      buildNestedObject(entries.map((entry) => ({
-        path: entry.modulePath.split('/').map(toCamelCase),
-        value: `createController(${entry.importName})`,
-      }))),
-      4,
-    )
-
-    groupLines.push(`  ${group.name}: {\n${objectBody}\n  },`)
-  }
+    const objectBody = buildNestedObject(entries.map((entry) => ({
+      path: entry.modulePath.split('/').map(toCamelCase),
+      value: `createController(${entry.importName})`,
+    })))
+
+    if (group.name === 'controller') {
+      groupLines.push(indentObject(objectBody, 2))
+    } else {
+      groupLines.push(`  ${group.name}: {\n${indentObject(objectBody, 4)}\n  },`)
+    }
+  }
 
   const helperImport = imports.length > 0
     ? `import { createController } from 'jax-hono/core/controller'\n`
@@ -374,21 +425,29 @@ export type Models = typeof models
   writeGeneratedFile('models.generated.ts', content)
 }
 
-function generateServicesRegistry() {
-  const files = getFilesFromDirs(['services', 'service', 'modules'])
-    .filter((filePath) => isModuleFeatureFile(filePath, '.service'))
-  const imports: string[] = []
-  const entries: string[] = []
-
-  files.forEach((filePath) => {
-    const source = readFileSync(filePath, 'utf8')
-    const namedServiceClasses = [...source.matchAll(/\bexport\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*Service)\b/g)]
-      .map((match) => match[1])
-      .sort((left, right) => left.localeCompare(right))
-    const defaultServiceClass = source.match(/\bexport\s+default\s+class(?:\s+([a-zA-Z_$][a-zA-Z0-9_$]*))?/)
-    const defaultServiceName = defaultServiceClass
-      ? defaultServiceClass[1] ?? `${toPascalCase(toModulePath('services', filePath))}Service`
-      : ''
+function generateServicesRegistry() {
+  const files = [
+    ...getFilesFromDirs(['services', 'service', 'modules'])
+      .filter((filePath) => isModuleFeatureFile(filePath, '.service'))
+      .map((filePath) => ({ filePath })),
+    ...getEnabledPluginFiles('.service'),
+  ]
+  const imports: string[] = []
+  const entries: string[] = []
+
+  files.forEach((item) => {
+    const { filePath } = item
+    const source = readFileSync(filePath, 'utf8')
+    const namedServiceClasses = [...source.matchAll(/\bexport\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*Service)\b/g)]
+      .map((match) => match[1])
+      .sort((left, right) => left.localeCompare(right))
+    const defaultServiceClass = source.match(/\bexport\s+default\s+class(?:\s+([a-zA-Z_$][a-zA-Z0-9_$]*))?/)
+    const fallbackServicePath = 'name' in item
+      ? toPluginModulePath(item.name, item.rootDir, filePath, ['.service'])
+      : toModulePath('services', filePath)
+    const defaultServiceName = defaultServiceClass
+      ? defaultServiceClass[1] ?? `${toPascalCase(fallbackServicePath)}Service`
+      : ''
     const defaultImportName = defaultServiceName
       ? toIdentifier([defaultServiceName, 'Default'])
       : ''
@@ -420,8 +479,58 @@ ${entries.join('\n')}
 export type Services = ReturnType<typeof createServices>
 `
 
-  writeGeneratedFile('services.generated.ts', content)
-}
+  writeGeneratedFile('services.generated.ts', content)
+}
+
+function generateCronsRegistry() {
+  const files = [
+    ...getFilesFromDirs(['cron', 'crons'])
+      .filter((filePath) => basename(filePath) !== 'index.ts')
+      .map((filePath) => ({
+        modulePath: toModulePath(filePath.includes(`${srcDir}/crons/`) ? 'crons' : 'cron', filePath, ['.cron']),
+        filePath,
+      })),
+    ...getFilesFromDirs(['modules'])
+      .filter((filePath) => isModuleFeatureFile(filePath, '.cron'))
+      .map((filePath) => ({
+        modulePath: toModulePath('modules', filePath, ['.cron']),
+        filePath,
+      })),
+    ...getEnabledPluginFiles('.cron')
+      .map(({ name, rootDir, filePath }) => ({
+        modulePath: toPluginModulePath(name, rootDir, filePath, ['.cron']),
+        filePath,
+      })),
+  ]
+    .filter(({ filePath }) => hasCronExport(filePath))
+    .filter((item, index, list) => {
+      return list.findIndex((row) => row.filePath === item.filePath) === index
+    })
+    .sort((left, right) => left.modulePath.localeCompare(right.modulePath))
+
+  const imports = files.map((item, index) => {
+    return `import * as ${toIdentifier(['cron', item.modulePath, String(index)])} from '${toImportPath(item.filePath)}'`
+  })
+  const entries = files.map((item, index) => {
+    const importName = toIdentifier(['cron', item.modulePath, String(index)])
+
+    return `  { name: ${JSON.stringify(item.modulePath)}, module: ${importName} },`
+  })
+  const content = `${generatedHeader}${imports.length > 0 ? `${imports.join('\n')}\n\n` : ''}
+export const cronModules = [
+${entries.join('\n')}
+] as const
+`
+
+  writeGeneratedFile('crons.generated.ts', content)
+}
+
+function hasCronExport(filePath: string) {
+  const source = readFileSync(filePath, 'utf8')
+
+  return /\bexport\s+default\b/.test(source)
+    || /\bexport\s+const\s+(?:cron|jobs)\b/.test(source)
+}
 
 function findBalancedObject(source: string, startIndex: number) {
   let depth = 0
@@ -546,7 +655,7 @@ function normalizePluginPackage(packageName: string, configFile: string) {
   return normalized
 }
 
-function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]) {
+function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]) {
   const merged = new Map<string, Exclude<PluginConfigItem, false>>()
 
   for (const { filePath, config } of configs) {
@@ -573,18 +682,71 @@ function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]
 
       return item.enable === true && typeof item.package === 'string' && item.package.length > 0
     })
-    .sort(([left], [right]) => left.localeCompare(right))
-}
+    .sort(([left], [right]) => left.localeCompare(right))
+}
+
+function getEnabledPluginConfigItems() {
+  return mergePluginConfig([
+    { filePath: join(packageDir, 'plugins/config.ts'), config: readPluginConfig(join(packageDir, 'plugins/config.ts')) },
+    { filePath: join(srcDir, 'config/plugin.ts'), config: readPluginConfig(join(srcDir, 'config/plugin.ts')) },
+  ])
+}
+
+function resolvePluginPackageDir(packageName: string) {
+  const resolved = resolvePluginPackage(packageName)
+
+  return statSync(resolved).isDirectory()
+    ? resolved
+    : dirname(resolved)
+}
+
+function resolvePluginPackage(packageName: string) {
+  if (isAbsolute(packageName)) {
+    return packageName
+  }
+
+  if (packageName.startsWith('./') || packageName.startsWith('../')) {
+    return resolve(projectDir, packageName)
+  }
+
+  if (packageName.startsWith('jax-hono/')) {
+    const packagePath = packageName.slice('jax-hono/'.length)
+    const directPath = join(packageDir, packagePath)
+
+    if (existsSync(directPath)) {
+      return directPath
+    }
+
+    const indexPath = join(directPath, 'index.ts')
+
+    if (existsSync(indexPath)) {
+      return indexPath
+    }
+  }
+
+  return projectRequire.resolve(packageName)
+}
+
+function getEnabledPlugins(): EnabledPlugin[] {
+  return getEnabledPluginConfigItems()
+    .map(([name, item]) => {
+      const rootDir = resolvePluginPackageDir(item.package)
+
+      return {
+        name,
+        packageName: item.package,
+        rootDir,
+      }
+    })
+    .filter((plugin) => existsSync(plugin.rootDir))
+}
 
 function serializePluginOptions(options: unknown) {
   return options === undefined ? '' : `, options: ${JSON.stringify(options)}`
 }
 
-function generatePluginContextRegistry() {
-  const enabledPlugins = mergePluginConfig([
-    { filePath: join(packageDir, 'plugins/config.ts'), config: readPluginConfig(join(packageDir, 'plugins/config.ts')) },
-    { filePath: join(srcDir, 'config/plugin.ts'), config: readPluginConfig(join(srcDir, 'config/plugin.ts')) },
-  ])
+function generatePluginContextRegistry() {
+  const enabledPlugins = getEnabledPluginConfigItems()
   const imports = enabledPlugins.map(([name, item]) => {
     return `import ${toIdentifier(['plugin', name])} from ${JSON.stringify(item.package)}`
   })
@@ -606,13 +768,14 @@ ${moduleEntries.join('\n')}
   writeGeneratedFile('plugins.generated.ts', content)
 }
 
-export function generateRegistry() {
-  generateControllersRegistry()
-  generateMiddlewaresRegistry()
-  generateModelsRegistry()
-  generateServicesRegistry()
-  generatePluginContextRegistry()
-}
+export function generateRegistry() {
+  generateControllersRegistry()
+  generateMiddlewaresRegistry()
+  generateModelsRegistry()
+  generateServicesRegistry()
+  generateCronsRegistry()
+  generatePluginContextRegistry()
+}
 
 if (import.meta.main) {
   generateRegistry()

package/core/app.ts

@@ -2,10 +2,12 @@ import { createHono, createApi } from './hono';
 import { registerCrudRoutes } from '../helpers/crud';
 import config from '../config';
 import type { Config } from '../config';
-import { pluginModules } from '../generated/plugins.generated';
-import type { models as generatedModels } from '../generated/models.generated';
-import type { createServices as generatedCreateServices } from '../generated/services.generated';
-import { runWithJaxContext } from './controller';
+import { pluginModules } from '../generated/plugins.generated';
+import { cronModules } from '../generated/crons.generated';
+import type { models as generatedModels } from '../generated/models.generated';
+import type { createServices as generatedCreateServices } from '../generated/services.generated';
+import { runWithJaxContext } from './controller';
+import { startCronJobs, stopCronJobs } from './cron';
 import { requestLog } from '../middleware/request-log';
 import type { Hono } from 'hono';
 import type { JaxHono } from './hono';
@@ -65,7 +67,8 @@ export function createApp(deps: AppRuntimeDeps): JaxHono {
     service: undefined as unknown as Services,
     plugin: {} as Plugins
   };
-  const activePlugins: ActivePlugin[] = [];
+  const activePlugins: ActivePlugin[] = [];
+  let activeCrons: ReturnType<typeof startCronJobs> = [];
 
   ctx.service = deps.createServices(ctx);
   app.jax = ctx;
@@ -91,16 +94,19 @@ export function createApp(deps: AppRuntimeDeps): JaxHono {
   ).then(async (plugins) => {
     activePlugins.push(...plugins.filter((plugin): plugin is ActivePlugin => Boolean(plugin)));
 
-    printEnabledPlugins(activePlugins);
-
-    await Promise.all(activePlugins.map((plugin) => runPluginReadySafely(plugin, ctx)));
-  });
+    printEnabledPlugins(activePlugins);
+
+    await Promise.all(activePlugins.map((plugin) => runPluginReadySafely(plugin, ctx)));
+
+    activeCrons = startCronJobs(cronModules, ctx);
+  });
 
   app.ready = ready;
   app.close = async () => {
-    await ready.catch(() => undefined);
-    await closePluginsSafely(activePlugins, ctx);
-  };
+    await ready.catch(() => undefined);
+    stopCronJobs(activeCrons);
+    await closePluginsSafely(activePlugins, ctx);
+  };
 
   return app;
 }

package/core/cron.ts

@@ -0,0 +1,151 @@
+import type { AppContext } from './app';
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type CronRunContext = AppContext & {
+  signal: AbortSignal;
+};
+
+export type CronSchedule = {
+  /**
+   * Cron expression supported by Bun.cron.
+   */
+  cron: string;
+  /**
+   * Run once immediately after the app is ready.
+   */
+  immediate?: boolean;
+};
+
+export type CronJob = CronSchedule & {
+  name?: string;
+  run: (ctx: CronRunContext) => MaybePromise<void>;
+};
+
+type CronModule =
+  | CronJob
+  | CronJob[]
+  | {
+      default?: CronJob | CronJob[];
+      cron?: CronJob | CronJob[];
+      jobs?: CronJob[];
+    };
+
+type CronModuleItem = {
+  name: string;
+  module: CronModule;
+};
+
+type ActiveCron = {
+  name: string;
+  cron: string;
+  nextRunAt?: Date;
+  stop: () => void;
+};
+
+export function defineCron(job: CronJob) {
+  return job;
+}
+
+export function startCronJobs(items: readonly CronModuleItem[], ctx: AppContext) {
+  const active: ActiveCron[] = [];
+
+  for (const item of items) {
+    for (const job of resolveCronJobs(item.module)) {
+      active.push(startCronJob(item.name, job, ctx));
+    }
+  }
+
+  printCronJobs(active);
+
+  return active;
+}
+
+export function stopCronJobs(items: readonly ActiveCron[]) {
+  for (const item of [...items].reverse()) {
+    item.stop();
+  }
+}
+
+function resolveCronJobs(module: CronModule): CronJob[] {
+  if (Array.isArray(module)) {
+    return module;
+  }
+
+  if (isCronJob(module)) {
+    return [module];
+  }
+
+  const jobs = module.default ?? module.cron ?? module.jobs ?? [];
+
+  return Array.isArray(jobs) ? jobs : [jobs];
+}
+
+function isCronJob(value: unknown): value is CronJob {
+  return Boolean(value && typeof value === 'object' && typeof (value as CronJob).run === 'function');
+}
+
+function startCronJob(moduleName: string, job: CronJob, appContext: AppContext): ActiveCron {
+  const name = job.name || moduleName;
+  const controller = new AbortController();
+  let running = false;
+
+  const run = async () => {
+    if (running || controller.signal.aborted) {
+      return;
+    }
+
+    running = true;
+
+    try {
+      await job.run({ ...appContext, signal: controller.signal });
+    } catch (error) {
+      console.error(`[cron] ${name} failed:`, error);
+    } finally {
+      running = false;
+    }
+  };
+  const cronJob = Bun.cron(job.cron, () => {
+    void run();
+  });
+
+  if (job.immediate) {
+    void run();
+  }
+
+  return {
+    name,
+    cron: job.cron,
+    nextRunAt: getNextRunAt(job.cron),
+    stop() {
+      controller.abort();
+      cronJob.stop();
+    },
+  };
+}
+
+function getNextRunAt(expression: string) {
+  try {
+    return Bun.cron.parse(expression) ?? undefined;
+  } catch (error) {
+    console.error(`[cron] invalid expression ${expression}:`, error);
+    return undefined;
+  }
+}
+
+function printCronJobs(items: readonly ActiveCron[]) {
+  if (items.length === 0) {
+    console.log('[cron] enabled: none');
+    return;
+  }
+
+  console.log('[cron] enabled:');
+
+  for (const item of items) {
+    const nextRunAt = item.nextRunAt
+      ? `${item.nextRunAt.toLocaleString()} (${item.nextRunAt.toISOString()})`
+      : 'unknown';
+
+    console.log(`  - ${item.name} (${item.cron}) next: ${nextRunAt}`);
+  }
+}

package/docs/agent.md

@@ -0,0 +1,150 @@
+# Agent 维护说明
+
+这份文档给 Codex、Claude 或其他代码代理阅读，用来说明维护 `jax-hono` 时的默认规则。
+
+## 本地 link 规则
+
+`jax-hono` 是用户自己维护的框架，常通过 `jax link` 链接到业务工程的 `node_modules/jax-hono`。
+
+如果在业务工程中需要修改 `jax-hono` 行为，先检查依赖是否已经 link 到本地源码目录。不要把它当成一次性的第三方 `node_modules` 临时补丁。
+
+在 Windows PowerShell 中，可以在业务仓库根目录查找所有 `jax-hono` 依赖：
+
+```powershell
+Get-ChildItem -Path . -Directory -Recurse -Filter jax-hono |
+  Where-Object { $_.FullName -match '\\node_modules\\jax-hono$' } |
+  Format-List LinkType,Target,FullName
+```
+
+如果 `LinkType` 是 `Junction` 或 `SymbolicLink`，直接修改 `Target` 指向的 `jax-hono` 源码目录。
+
+如果没有 link，先执行：
+
+```powershell
+jax link
+```
+
+然后再次确认 link 状态，再修改框架源码。
+
+## 修改生成器后的验证
+
+修改 `build/generate-registry.ts`、`build/generate-config.ts` 等生成逻辑后，需要在使用方工程里重新生成。
+
+常见命令：
+
+```powershell
+bun run setup
+```
+
+然后检查业务工程中的生成结果，例如：
+
+```text
+generated/controllers.generated.ts
+generated/models.generated.ts
+generated/services.generated.ts
+generated/middlewares.generated.ts
+generated/plugins.generated.ts
+```
+
+如果业务仓库里有多个工程都依赖 `jax-hono`，分别查看各工程的 `package.json`，运行它们自己的 setup/build 命令。
+
+## 插件生成约定
+
+生成器只扫描已启用插件。插件启用来源包括：
+
+- `jax-hono/plugins/config.ts`
+- 使用方工程的 `src/config/plugin.ts`
+
+未启用插件不应进入生成结果，避免构建解析未启用插件的运行时依赖。
+
+已启用插件中的约定文件会进入生成器：
+
+- `*.controller.ts` 注册到 `controllers` 根对象
+- `*.service.ts` 注册到 `services.generated.ts`
+- `*.cron.ts` 注册到 `crons.generated.ts`，由框架统一启动/停止
+
+例如启用插件 `foo` 后：
+
+```text
+plugins/foo/foo.controller.ts
+plugins/foo/foo-cache.service.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+可生成：
+
+```ts
+controllers.foo
+service.fooCache
+```
+
+Cron 文件可以使用 `defineCron`：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'foo-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
+## Controller 注册约定
+
+生成器需要保持不同命名空间的边界清晰：
+
+- `*.backend.ts` 注册到 `controllers.backend`
+- `*.api.ts` 注册到 `controllers.api`
+- `*.open.ts` 注册到 `controllers.open`
+- `*.client.ts` 注册到 `controllers.client`
+- `*.controller.ts` 注册到 `controllers` 根对象
+
+`.controller.ts` 表示通用 Controller，供 backend/api/open/client 等不同路由复用，不应自动归入 `controllers.backend`。
+
+例如：
+
+```text
+src/modules/oss/oss.controller.ts
+src/modules/oss/oss-bucket.controller.ts
+```
+
+应生成：
+
+```ts
+controllers.oss
+controllers.ossBucket
+```
+
+如果需要后台专用 Controller，使用：
+
+```text
+src/modules/foo/foo.backend.ts
+```
+
+应生成：
+
+```ts
+controllers.backend.foo
+```
+
+## 模块路径命名
+
+模块内文件名如果以模块目录名开头，生成 key 时可以去掉重复前缀：
+
+```text
+src/modules/oss/oss.controller.ts        -> controllers.oss
+src/modules/oss/oss-bucket.controller.ts -> controllers.ossBucket
+```
+
+不要生成成：
+
+```ts
+controllers.oss.oss
+controllers.oss.ossBucket
+```
+
+这样业务侧调用会更自然，也更适合在不同路由层复用。

package/docs/jax.md

@@ -91,9 +91,10 @@ export default definePlugin({
 - `generated/config.ts`
 - `generated/controllers.generated.ts`
 - `generated/middlewares.generated.ts`
-- `generated/models.generated.ts`
-- `generated/plugins.generated.ts`
-- `generated/services.generated.ts`
+- `generated/models.generated.ts`
+- `generated/plugins.generated.ts`
+- `generated/services.generated.ts`
+- `generated/crons.generated.ts`
 
 业务代码不要手动编辑 `generated` 目录。
 
@@ -259,7 +260,42 @@ Service 中推荐使用：
 
 新增文件后，如果业务侧需要使用，应优先在对应子入口导出，例如 `src/jax/utils/index.ts`、`src/jax/errors/index.ts`。只有框架核心 API 才放到 `src/jax/index.ts`。
 
-内置插件配置放在 `src/jax/plugins/config.ts`，内置插件实现放在 `src/jax/plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只读取插件配置，不扫描插件目录。
+内置插件配置放在 `plugins/config.ts`，内置插件实现放在 `plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只扫描已启用插件中的约定文件，不扫描未启用插件。
+
+已启用插件可以提供：
+
+- `*.controller.ts`：注册到 `controllers` 根对象
+- `*.service.ts`：注册到 `services.generated.ts`
+- `*.cron.ts`：注册到 `crons.generated.ts`，由框架统一启动/停止
+
+未启用插件不会进入生成结果，也不会让构建解析它的运行时依赖。
+
+### `cron`
+
+定时任务可以放在项目根级 `src/cron` / `src/crons` 目录，也可以放在模块或已启用插件中：
+
+```text
+src/cron/report.cron.ts
+src/modules/oss/oss-trash.cron.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+Cron 文件导出 `defineCron()`、`cron` 或 `jobs` 即可被生成器识别：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'daily-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
+框架会在应用 ready 后统一启动定时任务，在 `app.close()` 时统一停止，不需要每个任务在入口文件手动声明。
 
 ## 常用命令
 

package/index.ts

@@ -61,9 +61,11 @@ export type { AppContext, AppPlugin } from './core/app';
 export type { Config, JaxConfig } from './config';
 export { ApiController } from './core/api-controller';
 export { Controller } from './core/controller';
-export { Service } from './core/service';
-export type { ServiceContext } from './core/service';
-export type { Services } from './generated/services.generated';
+export { Service } from './core/service';
+export type { ServiceContext } from './core/service';
+export { defineCron } from './core/cron';
+export type { CronJob, CronRunContext, CronSchedule } from './core/cron';
+export type { Services } from './generated/services.generated';
 export type { ApiFailResponse, ApiResponse, ApiSuccessResponse } from './middleware/api-response';
 
 export function createApp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jax-hono",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Lightweight framework layer on top of Hono, built for Bun",
   "type": "module",
   "main": "./index.ts",

package/utils/crypto.ts

@@ -4,6 +4,12 @@ export function md5(value: string) {
   return createHash('md5').update(value).digest('hex');
 }
 
-export function createToken(byteLength = 24) {
-  return randomBytes(byteLength).toString('hex');
-}
+export function createToken(byteLength = 24) {
+  return randomBytes(byteLength).toString('hex');
+}
+
+export function nonceStr(length: number) {
+  return randomBytes(Math.ceil(length / 2))
+    .toString('hex')
+    .slice(0, length);
+}

package/utils/index.ts

@@ -1,5 +1,7 @@
 export * from "./array";
 export * from "./async";
-export * from "./crypto";
-export * from "./regexp";
-export * from "./transform";
+export * from "./crypto";
+export * from "./order";
+export * from "./regexp";
+export * from "./transform";
+export * from "./validate";

package/utils/order.ts

@@ -0,0 +1,5 @@
+import dayjs from 'dayjs';
+
+export function getOrderNo(prefix = '') {
+  return `${prefix}${dayjs().format('YYYYMMDDHHmmssSSS')}${Math.floor(Math.random() * 9000 + 1000)}`;
+}

package/utils/regexp.ts

@@ -12,6 +12,14 @@
  * escapeRegex('price$')         // => 'price\\$'
  * escapeRegex(123)              // => '123'
  */
-export function escapeRegex(value: unknown) {
-  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+export function escapeRegex(value: unknown) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function keywordRegex(keyword?: string) {
+  if (!keyword) {
+    return undefined;
+  }
+
+  return new RegExp(escapeRegex(keyword), 'i');
+}

package/utils/validate.ts

@@ -0,0 +1,7 @@
+export function requireFields(body: Record<string, unknown>, fields: string[]) {
+  for (const field of fields) {
+    if (body[field] === undefined || body[field] === null || body[field] === '') {
+      throw new Error(`缺少${field}`);
+    }
+  }
+}