@mokup/cli 1.0.5 → 1.0.7

package/dist/index.cjs

@@ -10,6 +10,7 @@ const esbuild = require('@mokup/shared/esbuild');
 const runtime = require('@mokup/runtime');
 const jsoncParser = require('@mokup/shared/jsonc-parser');
 const node = require('@mokup/server/node');
+const logger$1 = require('@mokup/shared/logger');
 const commander = require('commander');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -74,6 +75,7 @@ async function writeManifestModule(outDir, manifest) {
 }
 
 const configExtensions = [".ts", ".js", ".mjs", ".cjs"];
+const middlewareSymbol$1 = Symbol.for("mokup.config.middlewares");
 async function loadModule$1(file) {
   const ext = configExtensions.find((extension) => file.endsWith(extension));
   if (ext === ".cjs") {
@@ -134,7 +136,7 @@ async function loadConfig(file) {
   }
   return value;
 }
-function normalizeMiddlewares(value, source, log) {
+function normalizeMiddlewares(value, source, log, position) {
   if (!value) {
     return [];
   }
@@ -145,10 +147,22 @@ function normalizeMiddlewares(value, source, log) {
       log?.(`Invalid middleware in ${source}`);
       return;
     }
-    middlewares.push({ file: source, index });
+    middlewares.push({ file: source, index, position });
   });
   return middlewares;
 }
+function readMiddlewareMeta(config) {
+  const value = config[middlewareSymbol$1];
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const meta = value;
+  return {
+    pre: Array.isArray(meta.pre) ? meta.pre : [],
+    normal: Array.isArray(meta.normal) ? meta.normal : [],
+    post: Array.isArray(meta.post) ? meta.post : []
+  };
+}
 async function resolveDirectoryConfig(params) {
   const { file, rootDir, log, configCache, fileCache } = params;
   const resolvedRoot = pathe.normalize(rootDir);
@@ -167,7 +181,10 @@ async function resolveDirectoryConfig(params) {
     current = parent;
   }
   chain.reverse();
-  const merged = { middlewares: [] };
+  const merged = {};
+  const preMiddlewares = [];
+  const normalMiddlewares = [];
+  const postMiddlewares = [];
   for (const dir of chain) {
     const configPath = await findConfigFile(dir, fileCache);
     if (!configPath) {
@@ -203,12 +220,48 @@ async function resolveDirectoryConfig(params) {
     if (typeof config.exclude !== "undefined") {
       merged.exclude = config.exclude;
     }
-    const normalized = normalizeMiddlewares(config.middleware, configPath, log);
-    if (normalized.length > 0) {
-      merged.middlewares.push(...normalized);
+    const meta = readMiddlewareMeta(config);
+    const normalizedPre = normalizeMiddlewares(
+      meta?.pre,
+      configPath,
+      log,
+      "pre"
+    );
+    const normalizedNormal = normalizeMiddlewares(
+      meta?.normal,
+      configPath,
+      log,
+      "normal"
+    );
+    const normalizedLegacy = normalizeMiddlewares(
+      config.middleware,
+      configPath,
+      log,
+      "normal"
+    );
+    const normalizedPost = normalizeMiddlewares(
+      meta?.post,
+      configPath,
+      log,
+      "post"
+    );
+    if (normalizedPre.length > 0) {
+      preMiddlewares.push(...normalizedPre);
+    }
+    if (normalizedNormal.length > 0) {
+      normalMiddlewares.push(...normalizedNormal);
+    }
+    if (normalizedLegacy.length > 0) {
+      normalMiddlewares.push(...normalizedLegacy);
+    }
+    if (normalizedPost.length > 0) {
+      postMiddlewares.push(...normalizedPost);
     }
   }
-  return merged;
+  return {
+    ...merged,
+    middlewares: [...preMiddlewares, ...normalMiddlewares, ...postMiddlewares]
+  };
 }
 
 function toPosix(value) {
@@ -763,6 +816,40 @@ async function buildManifest(options = {}) {
   };
 }
 
+const middlewareSymbol = Symbol.for("mokup.config.middlewares");
+function createRegistry(list) {
+  return {
+    use: (...handlers) => {
+      list.push(...handlers);
+    }
+  };
+}
+function attachMetadata(config, meta) {
+  Object.defineProperty(config, middlewareSymbol, {
+    value: meta,
+    enumerable: false
+  });
+  return config;
+}
+function defineConfig(input) {
+  if (typeof input === "function") {
+    const pre = [];
+    const normal = [];
+    const post = [];
+    const context = {
+      pre: createRegistry(pre),
+      normal: createRegistry(normal),
+      post: createRegistry(post)
+    };
+    const result = input(context);
+    const config2 = result && typeof result === "object" ? result : {};
+    return attachMetadata(config2, { pre, normal, post });
+  }
+  const config = input && typeof input === "object" ? input : {};
+  return attachMetadata(config, { pre: [], normal: [], post: [] });
+}
+
+const logger = logger$1.createLogger();
 function collectValues(value, previous) {
   return [...previous ?? [], value];
 }
@@ -775,7 +862,7 @@ function toBuildOptions(options) {
   const buildOptions = {
     handlers: options.handlers !== false,
     log: (message) => {
-      console.log(message);
+      logger.info(message);
     }
   };
   if (options.dir && options.dir.length > 0) {
@@ -846,7 +933,7 @@ function createCli() {
     const host = entry.host ?? "localhost";
     const port = entry.port ?? 8080;
     const playgroundEnabled = playground !== false;
-    const playgroundPath = "/_mokup";
+    const playgroundPath = "/__mokup";
     const server = await node.createFetchServer({
       entries: entry,
       playground
@@ -860,9 +947,9 @@ function createCli() {
       (info) => {
         const resolvedHost = typeof info === "string" ? host : info?.address ?? host;
         const resolvedPort = typeof info === "string" ? port : info?.port ?? port;
-        console.log(`Mock server ready at http://${resolvedHost}:${resolvedPort}`);
+        logger.info(`Mock server ready at http://${resolvedHost}:${resolvedPort}`);
         if (playgroundEnabled) {
-          console.log(`Playground at http://${resolvedHost}:${resolvedPort}${playgroundPath}`);
+          logger.info(`Playground at http://${resolvedHost}:${resolvedPort}${playgroundPath}`);
         }
       }
     );
@@ -904,4 +991,5 @@ async function runCli(argv = process__default.argv) {
 
 exports.buildManifest = buildManifest;
 exports.createCli = createCli;
+exports.defineConfig = defineConfig;
 exports.runCli = runCli;

package/dist/index.d.cts

@@ -1,25 +1,264 @@
 import { Manifest } from '@mokup/runtime';
+import { MiddlewareHandler } from '@mokup/shared/hono';
 import { Command } from 'commander';
 
+/**
+ * Options for building a mokup manifest.
+ *
+ * @example
+ * import type { BuildOptions } from '@mokup/cli'
+ *
+ * const options: BuildOptions = {
+ *   dir: 'mock',
+ *   outDir: '.mokup',
+ * }
+ */
 interface BuildOptions {
+    /**
+     * Directory or directories to scan for mock files.
+     *
+     * @default "mock"
+     */
     dir?: string | string[];
+    /**
+     * Output directory for manifest artifacts.
+     *
+     * @default ".mokup"
+     */
     outDir?: string;
+    /**
+     * URL prefix to apply to generated routes.
+     *
+     * @default ""
+     */
     prefix?: string;
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
     include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
     exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes.
+     *
+     * @default ["."]
+     */
     ignorePrefix?: string | string[];
+    /**
+     * Emit handler bundles for module-based responses.
+     *
+     * @default true
+     */
     handlers?: boolean;
+    /**
+     * Project root used to resolve paths.
+     *
+     * @default process.cwd()
+     */
     root?: string;
+    /**
+     * Optional logger for build messages.
+     *
+     * @default undefined
+     */
     log?: (message: string) => void;
 }
+/**
+ * Route rule shape used in build-time resolution.
+ *
+ * @example
+ * import type { RouteRule } from '@mokup/cli'
+ *
+ * const rule: RouteRule = { handler: { ok: true } }
+ */
+interface RouteRule {
+    /** Route handler or static value. */
+    handler: unknown;
+    /**
+     * Enable or disable this rule.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Override response status code.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Delay in milliseconds before responding.
+     *
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Directory-level config used during manifest build.
+ *
+ * @example
+ * import type { RouteDirectoryConfig } from '@mokup/cli'
+ *
+ * const config: RouteDirectoryConfig = {
+ *   headers: { 'x-mokup': 'dir' },
+ * }
+ */
+interface RouteDirectoryConfig {
+    /**
+     * Headers applied to routes in this directory.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Default status code override.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Default delay in milliseconds.
+     *
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Enable or disable this directory.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Ignore prefixes applied to files in this directory.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Middleware for the directory.
+     *
+     * @default undefined
+     */
+    middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+/**
+ * Middleware execution position.
+ *
+ * @example
+ * import type { MiddlewarePosition } from '@mokup/cli'
+ *
+ * const position: MiddlewarePosition = 'pre'
+ */
+type MiddlewarePosition = 'pre' | 'normal' | 'post';
+/**
+ * Middleware registry used by defineConfig.
+ *
+ * @example
+ * import type { MiddlewareRegistry } from '@mokup/cli'
+ *
+ * const registry: MiddlewareRegistry = { use: () => {} }
+ */
+interface MiddlewareRegistry {
+    use: (...handlers: MiddlewareHandler[]) => void;
+}
 
+/**
+ * Build and write a mokup manifest to disk.
+ *
+ * @param options - Build options.
+ * @returns Build output metadata.
+ *
+ * @example
+ * import { buildManifest } from '@mokup/cli'
+ *
+ * const result = await buildManifest({ dir: 'mock', outDir: '.mokup' })
+ */
 declare function buildManifest(options?: BuildOptions): Promise<{
     manifest: Manifest;
     manifestPath: string;
 }>;
 
+type DefineConfigFactory = (context: {
+    pre: MiddlewareRegistry;
+    normal: MiddlewareRegistry;
+    post: MiddlewareRegistry;
+}) => RouteDirectoryConfig | void;
+/**
+ * Define a directory config with Hono-style middleware registration.
+ *
+ * @param input - Config object or factory callback.
+ * @returns Route directory config with middleware metadata.
+ *
+ * @example
+ * import { defineConfig } from '@mokup/cli'
+ *
+ * export default defineConfig(({ pre, normal, post }) => {
+ *   pre.use(async (c, next) => {
+ *     c.header('x-before', '1')
+ *     await next()
+ *   })
+ *
+ *   normal.use(async (_c, next) => {
+ *     await next()
+ *   })
+ *
+ *   post.use(async (c, next) => {
+ *     await next()
+ *     c.header('x-after', '1')
+ *   })
+ *
+ *   return { delay: 120 }
+ * })
+ */
+declare function defineConfig(input: RouteDirectoryConfig | DefineConfigFactory): RouteDirectoryConfig;
+
+/**
+ * Create the mokup CLI program instance.
+ *
+ * @returns A configured CLI program.
+ *
+ * @example
+ * import { createCli } from '@mokup/cli'
+ *
+ * const cli = createCli()
+ */
 declare function createCli(): Command;
+/**
+ * Run the mokup CLI with the provided argv.
+ *
+ * @param argv - CLI arguments.
+ * @returns Exit code or void.
+ *
+ * @example
+ * import { runCli } from '@mokup/cli'
+ *
+ * await runCli(['node', 'mokup', 'build', '--dir', 'mock'])
+ */
 declare function runCli(argv?: string[]): Promise<void>;
 
-export { buildManifest, createCli, runCli };
-export type { BuildOptions };
+export { buildManifest, createCli, defineConfig, runCli };
+export type { BuildOptions, MiddlewarePosition, MiddlewareRegistry, RouteDirectoryConfig, RouteRule };

package/dist/index.d.mts

@@ -1,25 +1,264 @@
 import { Manifest } from '@mokup/runtime';
+import { MiddlewareHandler } from '@mokup/shared/hono';
 import { Command } from 'commander';
 
+/**
+ * Options for building a mokup manifest.
+ *
+ * @example
+ * import type { BuildOptions } from '@mokup/cli'
+ *
+ * const options: BuildOptions = {
+ *   dir: 'mock',
+ *   outDir: '.mokup',
+ * }
+ */
 interface BuildOptions {
+    /**
+     * Directory or directories to scan for mock files.
+     *
+     * @default "mock"
+     */
     dir?: string | string[];
+    /**
+     * Output directory for manifest artifacts.
+     *
+     * @default ".mokup"
+     */
     outDir?: string;
+    /**
+     * URL prefix to apply to generated routes.
+     *
+     * @default ""
+     */
     prefix?: string;
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
     include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
     exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes.
+     *
+     * @default ["."]
+     */
     ignorePrefix?: string | string[];
+    /**
+     * Emit handler bundles for module-based responses.
+     *
+     * @default true
+     */
     handlers?: boolean;
+    /**
+     * Project root used to resolve paths.
+     *
+     * @default process.cwd()
+     */
     root?: string;
+    /**
+     * Optional logger for build messages.
+     *
+     * @default undefined
+     */
     log?: (message: string) => void;
 }
+/**
+ * Route rule shape used in build-time resolution.
+ *
+ * @example
+ * import type { RouteRule } from '@mokup/cli'
+ *
+ * const rule: RouteRule = { handler: { ok: true } }
+ */
+interface RouteRule {
+    /** Route handler or static value. */
+    handler: unknown;
+    /**
+     * Enable or disable this rule.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Override response status code.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Delay in milliseconds before responding.
+     *
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Directory-level config used during manifest build.
+ *
+ * @example
+ * import type { RouteDirectoryConfig } from '@mokup/cli'
+ *
+ * const config: RouteDirectoryConfig = {
+ *   headers: { 'x-mokup': 'dir' },
+ * }
+ */
+interface RouteDirectoryConfig {
+    /**
+     * Headers applied to routes in this directory.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Default status code override.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Default delay in milliseconds.
+     *
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Enable or disable this directory.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Ignore prefixes applied to files in this directory.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Middleware for the directory.
+     *
+     * @default undefined
+     */
+    middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+/**
+ * Middleware execution position.
+ *
+ * @example
+ * import type { MiddlewarePosition } from '@mokup/cli'
+ *
+ * const position: MiddlewarePosition = 'pre'
+ */
+type MiddlewarePosition = 'pre' | 'normal' | 'post';
+/**
+ * Middleware registry used by defineConfig.
+ *
+ * @example
+ * import type { MiddlewareRegistry } from '@mokup/cli'
+ *
+ * const registry: MiddlewareRegistry = { use: () => {} }
+ */
+interface MiddlewareRegistry {
+    use: (...handlers: MiddlewareHandler[]) => void;
+}
 
+/**
+ * Build and write a mokup manifest to disk.
+ *
+ * @param options - Build options.
+ * @returns Build output metadata.
+ *
+ * @example
+ * import { buildManifest } from '@mokup/cli'
+ *
+ * const result = await buildManifest({ dir: 'mock', outDir: '.mokup' })
+ */
 declare function buildManifest(options?: BuildOptions): Promise<{
     manifest: Manifest;
     manifestPath: string;
 }>;
 
+type DefineConfigFactory = (context: {
+    pre: MiddlewareRegistry;
+    normal: MiddlewareRegistry;
+    post: MiddlewareRegistry;
+}) => RouteDirectoryConfig | void;
+/**
+ * Define a directory config with Hono-style middleware registration.
+ *
+ * @param input - Config object or factory callback.
+ * @returns Route directory config with middleware metadata.
+ *
+ * @example
+ * import { defineConfig } from '@mokup/cli'
+ *
+ * export default defineConfig(({ pre, normal, post }) => {
+ *   pre.use(async (c, next) => {
+ *     c.header('x-before', '1')
+ *     await next()
+ *   })
+ *
+ *   normal.use(async (_c, next) => {
+ *     await next()
+ *   })
+ *
+ *   post.use(async (c, next) => {
+ *     await next()
+ *     c.header('x-after', '1')
+ *   })
+ *
+ *   return { delay: 120 }
+ * })
+ */
+declare function defineConfig(input: RouteDirectoryConfig | DefineConfigFactory): RouteDirectoryConfig;
+
+/**
+ * Create the mokup CLI program instance.
+ *
+ * @returns A configured CLI program.
+ *
+ * @example
+ * import { createCli } from '@mokup/cli'
+ *
+ * const cli = createCli()
+ */
 declare function createCli(): Command;
+/**
+ * Run the mokup CLI with the provided argv.
+ *
+ * @param argv - CLI arguments.
+ * @returns Exit code or void.
+ *
+ * @example
+ * import { runCli } from '@mokup/cli'
+ *
+ * await runCli(['node', 'mokup', 'build', '--dir', 'mock'])
+ */
 declare function runCli(argv?: string[]): Promise<void>;
 
-export { buildManifest, createCli, runCli };
-export type { BuildOptions };
+export { buildManifest, createCli, defineConfig, runCli };
+export type { BuildOptions, MiddlewarePosition, MiddlewareRegistry, RouteDirectoryConfig, RouteRule };

package/dist/index.d.ts

@@ -1,25 +1,264 @@
 import { Manifest } from '@mokup/runtime';
+import { MiddlewareHandler } from '@mokup/shared/hono';
 import { Command } from 'commander';
 
+/**
+ * Options for building a mokup manifest.
+ *
+ * @example
+ * import type { BuildOptions } from '@mokup/cli'
+ *
+ * const options: BuildOptions = {
+ *   dir: 'mock',
+ *   outDir: '.mokup',
+ * }
+ */
 interface BuildOptions {
+    /**
+     * Directory or directories to scan for mock files.
+     *
+     * @default "mock"
+     */
     dir?: string | string[];
+    /**
+     * Output directory for manifest artifacts.
+     *
+     * @default ".mokup"
+     */
     outDir?: string;
+    /**
+     * URL prefix to apply to generated routes.
+     *
+     * @default ""
+     */
     prefix?: string;
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
     include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
     exclude?: RegExp | RegExp[];
+    /**
+     * Ignore file or folder prefixes.
+     *
+     * @default ["."]
+     */
     ignorePrefix?: string | string[];
+    /**
+     * Emit handler bundles for module-based responses.
+     *
+     * @default true
+     */
     handlers?: boolean;
+    /**
+     * Project root used to resolve paths.
+     *
+     * @default process.cwd()
+     */
     root?: string;
+    /**
+     * Optional logger for build messages.
+     *
+     * @default undefined
+     */
     log?: (message: string) => void;
 }
+/**
+ * Route rule shape used in build-time resolution.
+ *
+ * @example
+ * import type { RouteRule } from '@mokup/cli'
+ *
+ * const rule: RouteRule = { handler: { ok: true } }
+ */
+interface RouteRule {
+    /** Route handler or static value. */
+    handler: unknown;
+    /**
+     * Enable or disable this rule.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Override response status code.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Delay in milliseconds before responding.
+     *
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Directory-level config used during manifest build.
+ *
+ * @example
+ * import type { RouteDirectoryConfig } from '@mokup/cli'
+ *
+ * const config: RouteDirectoryConfig = {
+ *   headers: { 'x-mokup': 'dir' },
+ * }
+ */
+interface RouteDirectoryConfig {
+    /**
+     * Headers applied to routes in this directory.
+     *
+     * @default {}
+     */
+    headers?: Record<string, string>;
+    /**
+     * Default status code override.
+     *
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Default delay in milliseconds.
+     *
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Enable or disable this directory.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Ignore prefixes applied to files in this directory.
+     *
+     * @default ["."]
+     */
+    ignorePrefix?: string | string[];
+    /**
+     * Include filter for files.
+     *
+     * @default undefined
+     */
+    include?: RegExp | RegExp[];
+    /**
+     * Exclude filter for files.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+    /**
+     * Middleware for the directory.
+     *
+     * @default undefined
+     */
+    middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+/**
+ * Middleware execution position.
+ *
+ * @example
+ * import type { MiddlewarePosition } from '@mokup/cli'
+ *
+ * const position: MiddlewarePosition = 'pre'
+ */
+type MiddlewarePosition = 'pre' | 'normal' | 'post';
+/**
+ * Middleware registry used by defineConfig.
+ *
+ * @example
+ * import type { MiddlewareRegistry } from '@mokup/cli'
+ *
+ * const registry: MiddlewareRegistry = { use: () => {} }
+ */
+interface MiddlewareRegistry {
+    use: (...handlers: MiddlewareHandler[]) => void;
+}
 
+/**
+ * Build and write a mokup manifest to disk.
+ *
+ * @param options - Build options.
+ * @returns Build output metadata.
+ *
+ * @example
+ * import { buildManifest } from '@mokup/cli'
+ *
+ * const result = await buildManifest({ dir: 'mock', outDir: '.mokup' })
+ */
 declare function buildManifest(options?: BuildOptions): Promise<{
     manifest: Manifest;
     manifestPath: string;
 }>;
 
+type DefineConfigFactory = (context: {
+    pre: MiddlewareRegistry;
+    normal: MiddlewareRegistry;
+    post: MiddlewareRegistry;
+}) => RouteDirectoryConfig | void;
+/**
+ * Define a directory config with Hono-style middleware registration.
+ *
+ * @param input - Config object or factory callback.
+ * @returns Route directory config with middleware metadata.
+ *
+ * @example
+ * import { defineConfig } from '@mokup/cli'
+ *
+ * export default defineConfig(({ pre, normal, post }) => {
+ *   pre.use(async (c, next) => {
+ *     c.header('x-before', '1')
+ *     await next()
+ *   })
+ *
+ *   normal.use(async (_c, next) => {
+ *     await next()
+ *   })
+ *
+ *   post.use(async (c, next) => {
+ *     await next()
+ *     c.header('x-after', '1')
+ *   })
+ *
+ *   return { delay: 120 }
+ * })
+ */
+declare function defineConfig(input: RouteDirectoryConfig | DefineConfigFactory): RouteDirectoryConfig;
+
+/**
+ * Create the mokup CLI program instance.
+ *
+ * @returns A configured CLI program.
+ *
+ * @example
+ * import { createCli } from '@mokup/cli'
+ *
+ * const cli = createCli()
+ */
 declare function createCli(): Command;
+/**
+ * Run the mokup CLI with the provided argv.
+ *
+ * @param argv - CLI arguments.
+ * @returns Exit code or void.
+ *
+ * @example
+ * import { runCli } from '@mokup/cli'
+ *
+ * await runCli(['node', 'mokup', 'build', '--dir', 'mock'])
+ */
 declare function runCli(argv?: string[]): Promise<void>;
 
-export { buildManifest, createCli, runCli };
-export type { BuildOptions };
+export { buildManifest, createCli, defineConfig, runCli };
+export type { BuildOptions, MiddlewarePosition, MiddlewareRegistry, RouteDirectoryConfig, RouteRule };

package/dist/index.mjs

@@ -8,6 +8,7 @@ import { build } from '@mokup/shared/esbuild';
 import { parseRouteTemplate, compareRouteScore } from '@mokup/runtime';
 import { parse } from '@mokup/shared/jsonc-parser';
 import { createFetchServer, serve } from '@mokup/server/node';
+import { createLogger } from '@mokup/shared/logger';
 import { Command } from 'commander';
 
 async function writeBundle(outDir, hasHandlers) {
@@ -67,6 +68,7 @@ async function writeManifestModule(outDir, manifest) {
 }
 
 const configExtensions = [".ts", ".js", ".mjs", ".cjs"];
+const middlewareSymbol$1 = Symbol.for("mokup.config.middlewares");
 async function loadModule$1(file) {
   const ext = configExtensions.find((extension) => file.endsWith(extension));
   if (ext === ".cjs") {
@@ -127,7 +129,7 @@ async function loadConfig(file) {
   }
   return value;
 }
-function normalizeMiddlewares(value, source, log) {
+function normalizeMiddlewares(value, source, log, position) {
   if (!value) {
     return [];
   }
@@ -138,10 +140,22 @@ function normalizeMiddlewares(value, source, log) {
       log?.(`Invalid middleware in ${source}`);
       return;
     }
-    middlewares.push({ file: source, index });
+    middlewares.push({ file: source, index, position });
   });
   return middlewares;
 }
+function readMiddlewareMeta(config) {
+  const value = config[middlewareSymbol$1];
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const meta = value;
+  return {
+    pre: Array.isArray(meta.pre) ? meta.pre : [],
+    normal: Array.isArray(meta.normal) ? meta.normal : [],
+    post: Array.isArray(meta.post) ? meta.post : []
+  };
+}
 async function resolveDirectoryConfig(params) {
   const { file, rootDir, log, configCache, fileCache } = params;
   const resolvedRoot = normalize(rootDir);
@@ -160,7 +174,10 @@ async function resolveDirectoryConfig(params) {
     current = parent;
   }
   chain.reverse();
-  const merged = { middlewares: [] };
+  const merged = {};
+  const preMiddlewares = [];
+  const normalMiddlewares = [];
+  const postMiddlewares = [];
   for (const dir of chain) {
     const configPath = await findConfigFile(dir, fileCache);
     if (!configPath) {
@@ -196,12 +213,48 @@ async function resolveDirectoryConfig(params) {
     if (typeof config.exclude !== "undefined") {
       merged.exclude = config.exclude;
     }
-    const normalized = normalizeMiddlewares(config.middleware, configPath, log);
-    if (normalized.length > 0) {
-      merged.middlewares.push(...normalized);
+    const meta = readMiddlewareMeta(config);
+    const normalizedPre = normalizeMiddlewares(
+      meta?.pre,
+      configPath,
+      log,
+      "pre"
+    );
+    const normalizedNormal = normalizeMiddlewares(
+      meta?.normal,
+      configPath,
+      log,
+      "normal"
+    );
+    const normalizedLegacy = normalizeMiddlewares(
+      config.middleware,
+      configPath,
+      log,
+      "normal"
+    );
+    const normalizedPost = normalizeMiddlewares(
+      meta?.post,
+      configPath,
+      log,
+      "post"
+    );
+    if (normalizedPre.length > 0) {
+      preMiddlewares.push(...normalizedPre);
+    }
+    if (normalizedNormal.length > 0) {
+      normalMiddlewares.push(...normalizedNormal);
+    }
+    if (normalizedLegacy.length > 0) {
+      normalMiddlewares.push(...normalizedLegacy);
+    }
+    if (normalizedPost.length > 0) {
+      postMiddlewares.push(...normalizedPost);
     }
   }
-  return merged;
+  return {
+    ...merged,
+    middlewares: [...preMiddlewares, ...normalMiddlewares, ...postMiddlewares]
+  };
 }
 
 function toPosix(value) {
@@ -756,6 +809,40 @@ async function buildManifest(options = {}) {
   };
 }
 
+const middlewareSymbol = Symbol.for("mokup.config.middlewares");
+function createRegistry(list) {
+  return {
+    use: (...handlers) => {
+      list.push(...handlers);
+    }
+  };
+}
+function attachMetadata(config, meta) {
+  Object.defineProperty(config, middlewareSymbol, {
+    value: meta,
+    enumerable: false
+  });
+  return config;
+}
+function defineConfig(input) {
+  if (typeof input === "function") {
+    const pre = [];
+    const normal = [];
+    const post = [];
+    const context = {
+      pre: createRegistry(pre),
+      normal: createRegistry(normal),
+      post: createRegistry(post)
+    };
+    const result = input(context);
+    const config2 = result && typeof result === "object" ? result : {};
+    return attachMetadata(config2, { pre, normal, post });
+  }
+  const config = input && typeof input === "object" ? input : {};
+  return attachMetadata(config, { pre: [], normal: [], post: [] });
+}
+
+const logger = createLogger();
 function collectValues(value, previous) {
   return [...previous ?? [], value];
 }
@@ -768,7 +855,7 @@ function toBuildOptions(options) {
   const buildOptions = {
     handlers: options.handlers !== false,
     log: (message) => {
-      console.log(message);
+      logger.info(message);
     }
   };
   if (options.dir && options.dir.length > 0) {
@@ -839,7 +926,7 @@ function createCli() {
     const host = entry.host ?? "localhost";
     const port = entry.port ?? 8080;
     const playgroundEnabled = playground !== false;
-    const playgroundPath = "/_mokup";
+    const playgroundPath = "/__mokup";
     const server = await createFetchServer({
       entries: entry,
       playground
@@ -853,9 +940,9 @@ function createCli() {
       (info) => {
         const resolvedHost = typeof info === "string" ? host : info?.address ?? host;
         const resolvedPort = typeof info === "string" ? port : info?.port ?? port;
-        console.log(`Mock server ready at http://${resolvedHost}:${resolvedPort}`);
+        logger.info(`Mock server ready at http://${resolvedHost}:${resolvedPort}`);
         if (playgroundEnabled) {
-          console.log(`Playground at http://${resolvedHost}:${resolvedPort}${playgroundPath}`);
+          logger.info(`Playground at http://${resolvedHost}:${resolvedPort}${playgroundPath}`);
         }
       }
     );
@@ -895,4 +982,4 @@ async function runCli(argv = process.argv) {
   await program.parseAsync(argv);
 }
 
-export { buildManifest, createCli, runCli };
+export { buildManifest, createCli, defineConfig, runCli };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mokup/cli",
   "type": "module",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "CLI for building mokup manifests and handlers.",
   "license": "MIT",
   "homepage": "https://mokup.icebreaker.top",
@@ -28,9 +28,9 @@
   ],
   "dependencies": {
     "commander": "^14.0.0",
-    "@mokup/runtime": "1.0.2",
-    "@mokup/shared": "1.0.1",
-    "@mokup/server": "1.1.2"
+    "@mokup/server": "1.1.4",
+    "@mokup/shared": "1.0.2",
+    "@mokup/runtime": "1.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",