@valkyrjaio/sindri 26.5.1 → 26.6.1

package/dist/bin/sindri.cjs

@@ -33,7 +33,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // node_modules/@ts-morph/common/dist/typescript.js
 var require_typescript = __commonJS({
   "node_modules/@ts-morph/common/dist/typescript.js"(exports2, module2) {
-    var ts13 = {};
+    var ts12 = {};
     ((module3) => {
       "use strict";
       var __defProp2 = Object.defineProperty;
@@ -211530,9 +211530,9 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
         };
       }
     })({ get exports() {
-      return ts13;
+      return ts12;
     }, set exports(v) {
-      ts13 = v;
+      ts12 = v;
       if (typeof module2 !== "undefined" && module2.exports) {
         module2.exports = v;
       }
@@ -216503,7 +216503,7 @@ var require_dist2 = __commonJS({
 var require_ts_morph_common = __commonJS({
   "node_modules/@ts-morph/common/dist/ts-morph-common.js"(exports2) {
     "use strict";
-    var ts13 = require_typescript();
+    var ts12 = require_typescript();
     var minimatch = require_commonjs3();
     var path$1 = require_path_browserify();
     var fs$1 = require("node:fs");
@@ -216533,7 +216533,7 @@ var require_ts_morph_common = __commonJS({
       n.default = e;
       return Object.freeze(n);
     }
-    var ts__namespace = /* @__PURE__ */ _interopNamespaceCompat(ts13);
+    var ts__namespace = /* @__PURE__ */ _interopNamespaceCompat(ts12);
     var minimatch__namespace = /* @__PURE__ */ _interopNamespaceCompat(minimatch);
     var path__default = /* @__PURE__ */ _interopDefaultCompat(path$1);
     var fs__namespace = /* @__PURE__ */ _interopNamespaceCompat(fs$1);
@@ -219643,85 +219643,85 @@ ${nodeLocation}` : message;
     Object.defineProperty(exports2, "DiagnosticCategory", {
       enumerable: true,
       get: function() {
-        return ts13.DiagnosticCategory;
+        return ts12.DiagnosticCategory;
       }
     });
     Object.defineProperty(exports2, "EmitHint", {
       enumerable: true,
       get: function() {
-        return ts13.EmitHint;
+        return ts12.EmitHint;
       }
     });
     Object.defineProperty(exports2, "LanguageVariant", {
       enumerable: true,
       get: function() {
-        return ts13.LanguageVariant;
+        return ts12.LanguageVariant;
       }
     });
     Object.defineProperty(exports2, "ModuleKind", {
       enumerable: true,
       get: function() {
-        return ts13.ModuleKind;
+        return ts12.ModuleKind;
       }
     });
     Object.defineProperty(exports2, "ModuleResolutionKind", {
       enumerable: true,
       get: function() {
-        return ts13.ModuleResolutionKind;
+        return ts12.ModuleResolutionKind;
       }
     });
     Object.defineProperty(exports2, "NewLineKind", {
       enumerable: true,
       get: function() {
-        return ts13.NewLineKind;
+        return ts12.NewLineKind;
       }
     });
     Object.defineProperty(exports2, "NodeFlags", {
       enumerable: true,
       get: function() {
-        return ts13.NodeFlags;
+        return ts12.NodeFlags;
       }
     });
     Object.defineProperty(exports2, "ObjectFlags", {
       enumerable: true,
       get: function() {
-        return ts13.ObjectFlags;
+        return ts12.ObjectFlags;
       }
     });
     Object.defineProperty(exports2, "ScriptKind", {
       enumerable: true,
       get: function() {
-        return ts13.ScriptKind;
+        return ts12.ScriptKind;
       }
     });
     Object.defineProperty(exports2, "ScriptTarget", {
       enumerable: true,
       get: function() {
-        return ts13.ScriptTarget;
+        return ts12.ScriptTarget;
       }
     });
     Object.defineProperty(exports2, "SymbolFlags", {
       enumerable: true,
       get: function() {
-        return ts13.SymbolFlags;
+        return ts12.SymbolFlags;
       }
     });
     Object.defineProperty(exports2, "SyntaxKind", {
       enumerable: true,
       get: function() {
-        return ts13.SyntaxKind;
+        return ts12.SyntaxKind;
       }
     });
     Object.defineProperty(exports2, "TypeFlags", {
       enumerable: true,
       get: function() {
-        return ts13.TypeFlags;
+        return ts12.TypeFlags;
       }
     });
     Object.defineProperty(exports2, "TypeFormatFlags", {
       enumerable: true,
       get: function() {
-        return ts13.TypeFormatFlags;
+        return ts12.TypeFormatFlags;
       }
     });
     exports2.ts = ts__namespace;
@@ -243006,6 +243006,96 @@ var AstReader = class _AstReader {
   getDecoratorArg(decorator, position) {
     return decorator.getArguments()[position];
   }
+  // -------------------------------------------------------------------------
+  // Object-literal decorator helpers — the shipped decorators accept a single
+  // options object (`@Route({ path, name, ... })`) rather than positional args.
+  // -------------------------------------------------------------------------
+  /**
+   * Return the decorator's first argument when it is an object literal, else undefined.
+   */
+  getDecoratorObjectArg(decorator) {
+    const arg = this.getDecoratorArg(decorator, 0);
+    if (arg === void 0) {
+      return void 0;
+    }
+    const tsNode = arg.compilerNode;
+    return import_ts_morph.ts.isObjectLiteralExpression(tsNode) ? tsNode : void 0;
+  }
+  /**
+   * Return the value expression of the named property on an object literal, or
+   * undefined when the property is absent (or is not a plain property assignment).
+   */
+  getObjectProp(obj, key) {
+    for (const prop of obj.properties) {
+      if (import_ts_morph.ts.isPropertyAssignment(prop) && this.propertyNameToString(prop.name) === key) {
+        return prop.initializer;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Resolve a property name node (identifier or string literal) to its text.
+   */
+  propertyNameToString(name) {
+    if (import_ts_morph.ts.isIdentifier(name) || import_ts_morph.ts.isStringLiteral(name)) {
+      return name.text;
+    }
+    return void 0;
+  }
+  /**
+   * Extract a string-valued object property, falling back to defaultValue.
+   */
+  getObjectStringProp(obj, key, useMap, currentFilePath, currentClass, defaultValue = "") {
+    const value = this.extractExprValue(this.getObjectProp(obj, key), useMap, currentFilePath, currentClass);
+    return typeof value === "string" ? value : defaultValue;
+  }
+  /**
+   * Extract a boolean-valued object property, falling back to defaultValue.
+   */
+  getObjectBoolProp(obj, key, useMap, currentFilePath, currentClass, defaultValue = false) {
+    const value = this.extractExprValue(this.getObjectProp(obj, key), useMap, currentFilePath, currentClass);
+    return typeof value === "boolean" ? value : defaultValue;
+  }
+  /**
+   * Extract a class-list object property (an array literal of class references),
+   * returning an empty array when the property is absent or not an array.
+   */
+  getObjectClassListProp(obj, key, useMap, currentFilePath, currentClass) {
+    const node = this.getObjectProp(obj, key);
+    if (node === void 0 || !import_ts_morph.ts.isArrayLiteralExpression(node)) {
+      return [];
+    }
+    return this.extractClassListFromArrayExpr(node, useMap, currentFilePath, currentClass);
+  }
+  /**
+   * Extract a string-list object property (an array literal of string values),
+   * returning an empty array when the property is absent or not an array.
+   */
+  getObjectStringListProp(obj, key, useMap, currentFilePath, currentClass) {
+    const node = this.getObjectProp(obj, key);
+    if (node === void 0 || !import_ts_morph.ts.isArrayLiteralExpression(node)) {
+      return [];
+    }
+    const values = [];
+    for (const element of node.elements) {
+      const value = this.extractExprValue(element, useMap, currentFilePath, currentClass);
+      if (typeof value === "string") {
+        values.push(value);
+      }
+    }
+    return values;
+  }
+  /**
+   * Extract a handler-reference object property (`[Class, 'method']`), returning
+   * undefined when the property is absent or not a two-element handler array.
+   */
+  getObjectHandlerProp(obj, key, useMap, currentFilePath, currentClass) {
+    const node = this.getObjectProp(obj, key);
+    if (node === void 0 || !import_ts_morph.ts.isArrayLiteralExpression(node)) {
+      return void 0;
+    }
+    return this.extractHandlerFromTsArray(node, useMap, currentFilePath, currentClass);
+  }
   /**
    * Convert a simple expression node to a scalar value or HandlerData.
    */
@@ -243062,7 +243152,12 @@ var AstReader = class _AstReader {
     if (array.elements.length !== 2) {
       return void 0;
     }
-    const classValue = this.extractExprValue(array.elements[0], useMap, currentFilePath, currentClass);
+    const classValue = this.extractExprValue(
+      this.unwrapClassThunk(array.elements[0]),
+      useMap,
+      currentFilePath,
+      currentClass
+    );
     const methodValue = this.extractExprValue(array.elements[1], useMap, currentFilePath, currentClass);
     if (typeof classValue !== "string" || classValue === "") {
       return void 0;
@@ -243072,10 +243167,35 @@ var AstReader = class _AstReader {
     }
     return new HandlerData(classValue, methodValue);
   }
+  /**
+   * Unwrap a class **thunk** to the class expression it returns —
+   * `() => HomeController` becomes `HomeController`.
+   *
+   * Every class reference in a decorator argument is authored as a thunk —
+   * `[() => SomeClass, 'method']` for a handler, `@Middleware(() => SomeClass)`
+   * for middleware — rather than as a bare class name. A TC39 Stage-3
+   * decorator runs while the class binding is still in its temporal dead zone,
+   * so naming the class directly throws at class-definition time on a circular
+   * or self-referential import. The thunk is purely a runtime deferral: the
+   * emitted cache is unchanged (`HttpRouteProvider.versionHandler`), so the
+   * reader simply looks through it. A bare class expression is returned
+   * untouched, and a block-bodied arrow (`() => { … }`) is left alone so it
+   * falls through to the usual "not a class reference" handling.
+   */
+  unwrapClassThunk(node) {
+    if (node === void 0) {
+      return node;
+    }
+    const tsNode = import_ts_morph.Node.isNode(node) ? node.compilerNode : node;
+    if (!import_ts_morph.ts.isArrowFunction(tsNode) || tsNode.parameters.length !== 0) {
+      return node;
+    }
+    return import_ts_morph.ts.isBlock(tsNode.body) ? node : tsNode.body;
+  }
   extractClassListFromArrayExpr(array, useMap, currentFilePath, currentClass = "") {
     const classes = [];
     for (const element of array.elements) {
-      const value = this.extractExprValue(element, useMap, currentFilePath, currentClass);
+      const value = this.extractExprValue(this.unwrapClassThunk(element), useMap, currentFilePath, currentClass);
       if (typeof value === "string" && value !== "") {
         classes.push(value);
       }
@@ -243705,8 +243825,8 @@ var WarningFormatter = class extends Formatter {
 
 // node_modules/@valkyrjaio/valkyrja/src/Valkyrja/Application/Constant/ApplicationInfo.ts
 var ApplicationInfo = class {
-  static VERSION = "26.5.1";
-  static VERSION_BUILD_DATE_TIME = "August 1 2026 07:55:41 MST";
+  static VERSION = "26.6.1";
+  static VERSION_BUILD_DATE_TIME = "August 2 2026 08:04:47 MST";
   static ASCII = `
                  _ _               _
      /\\   /\\__ _| | | ___   _ _ __(_) __ _
@@ -243815,8 +243935,8 @@ var Header = class extends Message {
 
 // src/Sindri/Constant/SindriInfo.ts
 var SindriInfo = class {
-  static VERSION = "26.5.1";
-  static VERSION_BUILD_DATE_TIME = "August 1 2026 14:12:56 MST";
+  static VERSION = "26.6.1";
+  static VERSION_BUILD_DATE_TIME = "August 2 2026 08:21:26 MST";
   static ICON = `    \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588
     \u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588
         \u2588\u2588\u2588\u2588
@@ -244292,10 +244412,12 @@ var CliRouteData = class {
 
 // src/Sindri/Ast/Data/Result/CliRouteAttributeResult.ts
 var CliRouteAttributeResult = class {
-  constructor(routes = {}) {
+  constructor(routes = {}, importMap = {}) {
     this.routes = routes;
+    this.importMap = importMap;
   }
   routes;
+  importMap;
 };
 
 // src/Sindri/Ast/CliRouteParameterReader.ts
@@ -244345,7 +244467,7 @@ var CliOptionParameterData = class {
 var CliRouteParameterReader = class extends AstReader {
   buildParameterArgs(data) {
     const args = [];
-    if (data.arguments.length > 0) {
+    if (data.arguments.length > 0 || data.options.length > 0) {
       args.push(this.buildArgumentListExpr(data.arguments));
     }
     if (data.options.length > 0) {
@@ -244374,26 +244496,30 @@ var CliRouteParameterReader = class extends AstReader {
     return options;
   }
   buildArgumentData(decorator, useMap, currentFilePath, currentClass) {
-    const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-    const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+    const obj = this.getDecoratorObjectArg(decorator);
+    if (obj === void 0) {
+      return null;
+    }
+    const name = this.getObjectStringProp(obj, "name", useMap, currentFilePath, currentClass);
+    const description = this.getObjectStringProp(obj, "description", useMap, currentFilePath, currentClass);
     if (name === "" || description === "") {
       return null;
     }
     return new CliArgumentParameterData(
       name,
       description,
-      this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass) || null,
-      this.extractStringArg(
-        decorator,
-        3,
+      this.getObjectStringProp(obj, "cast", useMap, currentFilePath, currentClass) || null,
+      this.getObjectStringProp(
+        obj,
+        "mode",
         useMap,
         currentFilePath,
         currentClass,
         "Valkyrja\\Cli\\Routing\\Enum\\ArgumentMode::OPTIONAL"
       ),
-      this.extractStringArg(
-        decorator,
-        4,
+      this.getObjectStringProp(
+        obj,
+        "valueMode",
         useMap,
         currentFilePath,
         currentClass,
@@ -244402,30 +244528,34 @@ var CliRouteParameterReader = class extends AstReader {
     );
   }
   buildOptionData(decorator, useMap, currentFilePath, currentClass) {
-    const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-    const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+    const obj = this.getDecoratorObjectArg(decorator);
+    if (obj === void 0) {
+      return null;
+    }
+    const name = this.getObjectStringProp(obj, "name", useMap, currentFilePath, currentClass);
+    const description = this.getObjectStringProp(obj, "description", useMap, currentFilePath, currentClass);
     if (name === "" || description === "") {
       return null;
     }
     return new CliOptionParameterData(
       name,
       description,
-      this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass),
-      this.extractStringArg(decorator, 3, useMap, currentFilePath, currentClass) || null,
-      this.extractStringArg(decorator, 4, useMap, currentFilePath, currentClass),
-      this.extractStringListArgFromDecorator(decorator, 5, useMap, currentFilePath, currentClass),
-      this.extractStringListArgFromDecorator(decorator, 6, useMap, currentFilePath, currentClass),
-      this.extractStringArg(
-        decorator,
-        7,
+      this.getObjectStringProp(obj, "valueDisplayName", useMap, currentFilePath, currentClass),
+      this.getObjectStringProp(obj, "cast", useMap, currentFilePath, currentClass) || null,
+      this.getObjectStringProp(obj, "defaultValue", useMap, currentFilePath, currentClass),
+      this.getObjectStringListProp(obj, "shortNames", useMap, currentFilePath, currentClass),
+      this.getObjectStringListProp(obj, "validValues", useMap, currentFilePath, currentClass),
+      this.getObjectStringProp(
+        obj,
+        "mode",
         useMap,
         currentFilePath,
         currentClass,
         "Valkyrja\\Cli\\Routing\\Enum\\OptionMode::OPTIONAL"
       ),
-      this.extractStringArg(
-        decorator,
-        8,
+      this.getObjectStringProp(
+        obj,
+        "valueMode",
         useMap,
         currentFilePath,
         currentClass,
@@ -244469,6 +244599,7 @@ var CliRouteParameterReader = class extends AstReader {
     } else {
       args.push(import_ts_morph5.ts.factory.createArrayLiteralExpression([]));
     }
+    args.push(import_ts_morph5.ts.factory.createArrayLiteralExpression([]));
     args.push(this.buildEnumCaseExpr(data.mode));
     args.push(this.buildEnumCaseExpr(data.valueMode));
     return this.buildNewExpr("Valkyrja\\Cli\\Routing\\Data\\OptionParameter", args);
@@ -244489,22 +244620,29 @@ var CliRouteAttributeReader = class extends RouteAttributeReader {
     }
     const { classDecl, useMap, currentClass } = context;
     const routes = {};
+    const routeData = {};
     for (const method of classDecl.getMethods()) {
       for (const decorator of this.findDecoratorsOnNode(method, "Route", useMap, filePath)) {
         const data = this.buildRouteData(decorator, method, useMap, filePath, currentClass);
         if (data !== null) {
           routes[data.name] = this.buildRouteExpr(data);
+          routeData[data.name] = data;
         }
       }
     }
-    return new CliRouteAttributeResult(routes);
+    const importMap = this.buildImportMap(routeData, useMap, filePath, currentClass);
+    return new CliRouteAttributeResult(routes, importMap);
   }
   getRouteHandlerDecoratorName() {
     return "RouteHandler";
   }
   buildRouteData(decorator, method, useMap, currentFilePath, currentClass) {
-    const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-    const description = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+    const obj = this.getDecoratorObjectArg(decorator);
+    if (obj === void 0) {
+      return null;
+    }
+    const name = this.getObjectStringProp(obj, "name", useMap, currentFilePath, currentClass);
+    const description = this.getObjectStringProp(obj, "description", useMap, currentFilePath, currentClass);
     if (name === "" || description === "") {
       return null;
     }
@@ -244514,16 +244652,13 @@ var CliRouteAttributeReader = class extends RouteAttributeReader {
       useMap,
       currentFilePath,
       currentClass,
-      this.extractClassListArgFromDecorator(decorator, 4, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 5, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 6, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 7, useMap, currentFilePath, currentClass)
+      this.getObjectClassListProp(obj, "middleware", useMap, currentFilePath, currentClass)
     );
     return new CliRouteData(
       updatedName,
       description,
-      this.updateHandler(method, useMap, currentFilePath, currentClass),
-      null,
+      this.resolveHandler(obj, method, useMap, currentFilePath, currentClass),
+      this.getObjectHandlerProp(obj, "helpText", useMap, currentFilePath, currentClass) ?? null,
       routeMatchedMiddleware,
       routeDispatchedMiddleware,
       throwableCaughtMiddleware,
@@ -244532,6 +244667,13 @@ var CliRouteAttributeReader = class extends RouteAttributeReader {
       this.parameterReader.updateOptions(method, useMap, currentFilePath, currentClass)
     );
   }
+  resolveHandler(obj, method, useMap, currentFilePath, currentClass) {
+    const fromObj = this.getObjectHandlerProp(obj, "handler", useMap, currentFilePath, currentClass);
+    if (fromObj !== void 0) {
+      return fromObj;
+    }
+    return this.updateHandler(method, useMap, currentFilePath, currentClass);
+  }
   updateName(name, method, useMap, currentFilePath, currentClass) {
     for (const decorator of this.findDecoratorsOnNode(method, "Name", useMap, currentFilePath)) {
       const override = this.extractExprValue(
@@ -244546,10 +244688,25 @@ var CliRouteAttributeReader = class extends RouteAttributeReader {
     }
     return name;
   }
-  updateMiddleware(method, useMap, currentFilePath, currentClass, routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware) {
+  updateMiddleware(method, useMap, currentFilePath, currentClass, middleware) {
+    let routeMatchedMiddleware = [];
+    let routeDispatchedMiddleware = [];
+    let throwableCaughtMiddleware = [];
+    let processExitingMiddleware = [];
+    for (const mwName of middleware) {
+      [routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, processExitingMiddleware] = this.classifyMiddleware(
+        mwName,
+        useMap,
+        currentFilePath,
+        routeMatchedMiddleware,
+        routeDispatchedMiddleware,
+        throwableCaughtMiddleware,
+        processExitingMiddleware
+      );
+    }
     for (const decorator of this.findDecoratorsOnNode(method, "Middleware", useMap, currentFilePath)) {
       const mwName = this.extractExprValue(
-        this.getDecoratorArg(decorator, 0),
+        this.unwrapClassThunk(this.getDecoratorArg(decorator, 0)),
         useMap,
         currentFilePath,
         currentClass
@@ -244608,6 +244765,31 @@ var CliRouteAttributeReader = class extends RouteAttributeReader {
       this.buildClassArrayExpr(data.processExitingMiddleware)
     ];
   }
+  /**
+   * Build the class-name → absolute-file-path map for every handler and
+   * help-text class the generated data cache references, so the generator can
+   * emit the matching import statements. (Middleware are emitted as string
+   * literals and therefore need no import.)
+   */
+  buildImportMap(routeData, useMap, currentFilePath, currentClass) {
+    const importMap = {};
+    for (const data of Object.values(routeData)) {
+      if (data.handler !== null) {
+        this.addClassImport(importMap, data.handler.class, useMap, currentFilePath, currentClass);
+      }
+      if (data.helpText !== null) {
+        this.addClassImport(importMap, data.helpText.class, useMap, currentFilePath, currentClass);
+      }
+    }
+    return importMap;
+  }
+  addClassImport(importMap, className, useMap, currentFilePath, currentClass) {
+    const shortName = className.slice(className.lastIndexOf("\\") + 1);
+    const filePath = shortName === currentClass ? currentFilePath : this.resolveImportToFilePath(shortName, useMap, currentFilePath);
+    if (filePath !== "") {
+      importMap[shortName] = filePath;
+    }
+  }
 };
 
 // src/Sindri/Ast/Data/Result/ComponentProviderResult.ts
@@ -244694,23 +244876,20 @@ var HttpRouteData = class {
 
 // src/Sindri/Ast/Data/Result/HttpRouteAttributeResult.ts
 var HttpRouteAttributeResult = class {
-  constructor(routes = {}, routeData = {}) {
+  constructor(routes = {}, routeData = {}, importMap = {}) {
     this.routes = routes;
     this.routeData = routeData;
+    this.importMap = importMap;
   }
   routes;
   routeData;
+  importMap;
 };
 
 // src/Sindri/Ast/HttpRouteMiddlewareReader.ts
-var import_ts_morph6 = __toESM(require_ts_morph(), 1);
 var HttpRouteMiddlewareReader = class extends AstReader {
-  extractInlineRequestMethods(decoratorArgs, useMap, namespace, currentClass) {
-    const requestMethodsArg = decoratorArgs[3];
-    if (requestMethodsArg === void 0 || !import_ts_morph6.ts.isArrayLiteralExpression(requestMethodsArg)) {
-      return [];
-    }
-    return this.extractClassListFromArrayExpr(requestMethodsArg, useMap, namespace, currentClass);
+  extractObjectRequestMethods(obj, useMap, namespace, currentClass) {
+    return this.getObjectClassListProp(obj, "requestMethods", useMap, namespace, currentClass);
   }
   updateRequestMethods(requestMethods, method, useMap, namespace, currentClass) {
     for (const decorator of this.findDecoratorsOnNode(method, "RequestMethod", useMap, namespace)) {
@@ -244729,9 +244908,37 @@ var HttpRouteMiddlewareReader = class extends AstReader {
     }
     return requestMethods;
   }
-  updateMiddleware(method, useMap, namespace, currentClass, routeMatchedMiddleware, routeDispatchedMiddleware, throwableCaughtMiddleware, sendingResponseMiddleware, responseSentMiddleware) {
+  updateMiddleware(method, useMap, namespace, currentClass, middleware) {
+    let routeMatchedMiddleware = [];
+    let routeDispatchedMiddleware = [];
+    let throwableCaughtMiddleware = [];
+    let sendingResponseMiddleware = [];
+    let responseSentMiddleware = [];
+    for (const mwName of middleware) {
+      [
+        routeMatchedMiddleware,
+        routeDispatchedMiddleware,
+        throwableCaughtMiddleware,
+        sendingResponseMiddleware,
+        responseSentMiddleware
+      ] = this.classifyMiddleware(
+        mwName,
+        useMap,
+        namespace,
+        routeMatchedMiddleware,
+        routeDispatchedMiddleware,
+        throwableCaughtMiddleware,
+        sendingResponseMiddleware,
+        responseSentMiddleware
+      );
+    }
     for (const decorator of this.findDecoratorsOnNode(method, "Middleware", useMap, namespace)) {
-      const mwName = this.extractExprValue(this.getDecoratorArg(decorator, 0), useMap, namespace, currentClass);
+      const mwName = this.extractExprValue(
+        this.unwrapClassThunk(this.getDecoratorArg(decorator, 0)),
+        useMap,
+        namespace,
+        currentClass
+      );
       if (typeof mwName !== "string" || mwName === "") {
         continue;
       }
@@ -244828,111 +245035,71 @@ var HttpRouteMiddlewareReader = class extends AstReader {
 };
 
 // src/Sindri/Ast/HttpRouteParameterReader.ts
-var import_ts_morph7 = __toESM(require_ts_morph(), 1);
+var import_ts_morph6 = __toESM(require_ts_morph(), 1);
 
 // src/Sindri/Ast/Data/HttpParameterData.ts
 var HttpParameterData = class {
-  constructor(name, regex, cast = null, isOptional = false, shouldCapture = true) {
+  constructor(name, regex, cast = null, isOptional = false, shouldCapture = true, defaultValue = null) {
     this.name = name;
     this.regex = regex;
     this.cast = cast;
     this.isOptional = isOptional;
     this.shouldCapture = shouldCapture;
+    this.defaultValue = defaultValue;
   }
   name;
   regex;
   cast;
   isOptional;
   shouldCapture;
+  defaultValue;
 };
 
 // src/Sindri/Ast/HttpRouteParameterReader.ts
 var HttpRouteParameterReader = class extends AstReader {
-  updateParameters(decoratorArgs, method, useMap, namespace, currentClass) {
-    return [
-      ...this.collectInlineParameters(decoratorArgs, useMap, namespace, currentClass),
-      ...this.collectAttributeParameters(method, useMap, namespace, currentClass),
-      ...this.collectMethodParamParameters(method, useMap, namespace, currentClass)
-    ];
-  }
-  buildParameterListExpr(parameters) {
-    const elements = parameters.map((p) => this.buildParameterExpr(p));
-    return import_ts_morph7.ts.factory.createArrayLiteralExpression(elements);
-  }
-  collectInlineParameters(decoratorArgs, useMap, currentFilePath, currentClass) {
-    const inlineArg = decoratorArgs[2];
-    if (inlineArg === void 0 || !import_ts_morph7.ts.isArrayLiteralExpression(inlineArg)) {
+  updateParameters(obj, useMap, namespace, currentClass) {
+    const node = this.getObjectProp(obj, "parameters");
+    if (node === void 0 || !import_ts_morph6.ts.isArrayLiteralExpression(node)) {
       return [];
     }
     const parameters = [];
-    for (const element of inlineArg.elements) {
-      if (!import_ts_morph7.ts.isNewExpression(element) || element.arguments === void 0) {
+    for (const element of node.elements) {
+      if (!import_ts_morph6.ts.isObjectLiteralExpression(element)) {
         continue;
       }
-      const param = this.buildParameterDataFromTsArgs(element.arguments, useMap, currentFilePath, currentClass);
-      if (param !== null) {
-        parameters.push(param);
-      }
-    }
-    return parameters;
-  }
-  collectAttributeParameters(method, useMap, currentFilePath, currentClass) {
-    const parameters = [];
-    for (const decorator of this.findDecoratorsOnNode(method, "Parameter", useMap, currentFilePath)) {
-      const param = this.buildParameterDataFromDecorator(decorator, useMap, currentFilePath, currentClass);
+      const param = this.buildParameterData(element, useMap, namespace, currentClass);
       if (param !== null) {
         parameters.push(param);
       }
     }
     return parameters;
   }
-  collectMethodParamParameters(method, useMap, currentFilePath, currentClass) {
-    const parameters = [];
-    for (const methodParam of method.getParameters()) {
-      for (const decorator of this.findDecoratorsOnNode(methodParam, "Parameter", useMap, currentFilePath)) {
-        const param = this.buildParameterDataFromDecorator(decorator, useMap, currentFilePath, currentClass);
-        if (param !== null) {
-          parameters.push(param);
-        }
-      }
-    }
-    return parameters;
+  buildParameterListExpr(parameters) {
+    const elements = parameters.map((p) => this.buildParameterExpr(p));
+    return import_ts_morph6.ts.factory.createArrayLiteralExpression(elements);
   }
-  buildParameterDataFromDecorator(decorator, useMap, currentFilePath, currentClass) {
-    const name = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-    const regex = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+  buildParameterData(obj, useMap, currentFilePath, currentClass) {
+    const name = this.getObjectStringProp(obj, "name", useMap, currentFilePath, currentClass);
+    const regex = this.getObjectStringProp(obj, "regex", useMap, currentFilePath, currentClass);
     if (name === "" || regex === "") {
       return null;
     }
+    const cast = this.getObjectStringProp(obj, "cast", useMap, currentFilePath, currentClass) || null;
     return new HttpParameterData(
       name,
       regex,
-      this.extractStringArg(decorator, 2, useMap, currentFilePath, currentClass) || null,
-      this.extractBoolArg(decorator, 3, useMap, currentFilePath, currentClass, false),
-      this.extractBoolArg(decorator, 4, useMap, currentFilePath, currentClass, true)
+      cast,
+      this.getObjectBoolProp(obj, "isOptional", useMap, currentFilePath, currentClass, false),
+      this.getObjectBoolProp(obj, "shouldCapture", useMap, currentFilePath, currentClass, true),
+      this.extractDefault(obj, useMap, currentFilePath, currentClass)
     );
   }
-  buildParameterDataFromTsArgs(args, useMap, currentFilePath, currentClass) {
-    const nameNode = args[0];
-    const regexNode = args[1];
-    if (nameNode === void 0 || regexNode === void 0) {
-      return null;
-    }
-    const name = this.extractExprValue(nameNode, useMap, currentFilePath, currentClass);
-    const regex = this.extractExprValue(regexNode, useMap, currentFilePath, currentClass);
-    if (typeof name !== "string" || name === "" || typeof regex !== "string" || regex === "") {
-      return null;
+  extractDefault(obj, useMap, currentFilePath, currentClass) {
+    const value = this.extractExprValue(this.getObjectProp(obj, "default"), useMap, currentFilePath, currentClass);
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return value;
     }
-    const castNode = args[2];
-    const castRaw = castNode !== void 0 ? this.extractExprValue(castNode, useMap, currentFilePath, currentClass) : null;
-    const cast = typeof castRaw === "string" && castRaw !== "" ? castRaw : null;
-    const isOptionalNode = args[3];
-    const isOptionalRaw = isOptionalNode !== void 0 ? this.extractExprValue(isOptionalNode, useMap, currentFilePath, currentClass) : false;
-    const isOptional = typeof isOptionalRaw === "boolean" ? isOptionalRaw : false;
-    const shouldCaptureNode = args[4];
-    const shouldCaptureRaw = shouldCaptureNode !== void 0 ? this.extractExprValue(shouldCaptureNode, useMap, currentFilePath, currentClass) : true;
-    const shouldCapture = typeof shouldCaptureRaw === "boolean" ? shouldCaptureRaw : true;
-    return new HttpParameterData(name, regex, cast, isOptional, shouldCapture);
+    return null;
   }
   buildParameterExpr(data) {
     const regexExpr = data.regex.includes("::") ? this.buildEnumCaseExpr(data.regex) : this.buildStringExpr(data.regex);
@@ -244943,8 +245110,20 @@ var HttpRouteParameterReader = class extends AstReader {
       this.buildBoolExpr(data.isOptional),
       this.buildBoolExpr(data.shouldCapture)
     ];
+    if (data.defaultValue !== null) {
+      args.push(this.buildScalarExpr(data.defaultValue));
+    }
     return this.buildNewExpr("Valkyrja\\Http\\Routing\\Data\\Parameter", args);
   }
+  buildScalarExpr(value) {
+    if (typeof value === "string") {
+      return this.buildStringExpr(value);
+    }
+    if (typeof value === "boolean") {
+      return this.buildBoolExpr(value);
+    }
+    return import_ts_morph6.ts.factory.createNumericLiteral(value);
+  }
 };
 
 // src/Sindri/Ast/HttpRouteAttributeReader.ts
@@ -245002,7 +245181,7 @@ var HttpRouteAttributeReader = class extends RouteAttributeReader {
     const routeData = {};
     for (const method of classDecl.getMethods()) {
       for (const decorator of this.findDecoratorsOnNode(method, "Route", useMap, currentFilePath)) {
-        const data = this.buildRouteData(
+        this.collectRoute(
           decorator,
           method,
           useMap,
@@ -245010,15 +245189,13 @@ var HttpRouteAttributeReader = class extends RouteAttributeReader {
           currentClass,
           classPathPrefix,
           classNamePrefix,
-          false
+          false,
+          routes,
+          routeData
         );
-        if (data !== null) {
-          routes[data.name] = this.buildRouteExpr(data);
-          routeData[data.name] = data;
-        }
       }
       for (const decorator of this.findDecoratorsOnNode(method, "DynamicRoute", useMap, currentFilePath)) {
-        const data = this.buildRouteData(
+        this.collectRoute(
           decorator,
           method,
           useMap,
@@ -245026,28 +245203,46 @@ var HttpRouteAttributeReader = class extends RouteAttributeReader {
           currentClass,
           classPathPrefix,
           classNamePrefix,
-          true
+          true,
+          routes,
+          routeData
         );
-        if (data !== null) {
-          routes[data.name] = this.buildRouteExpr(data);
-          routeData[data.name] = data;
-        }
       }
     }
-    return new HttpRouteAttributeResult(routes, routeData);
+    const importMap = this.buildImportMap(routeData, useMap, currentFilePath, currentClass);
+    return new HttpRouteAttributeResult(routes, routeData, importMap);
+  }
+  collectRoute(decorator, method, useMap, currentFilePath, currentClass, classPathPrefix, classNamePrefix, isDynamic, routes, routeData) {
+    const data = this.buildRouteData(
+      decorator,
+      method,
+      useMap,
+      currentFilePath,
+      currentClass,
+      classPathPrefix,
+      classNamePrefix,
+      isDynamic
+    );
+    if (data !== null) {
+      routes[data.name] = this.buildRouteExpr(data);
+      routeData[data.name] = data;
+    }
   }
   buildRouteData(decorator, method, useMap, currentFilePath, currentClass, classPathPrefix, classNamePrefix, isDynamic) {
-    const path6 = this.extractStringArg(decorator, 0, useMap, currentFilePath, currentClass);
-    const name = this.extractStringArg(decorator, 1, useMap, currentFilePath, currentClass);
+    const obj = this.getDecoratorObjectArg(decorator);
+    if (obj === void 0) {
+      return null;
+    }
+    const path6 = this.getObjectStringProp(obj, "path", useMap, currentFilePath, currentClass);
+    const name = this.getObjectStringProp(obj, "name", useMap, currentFilePath, currentClass);
     if (path6 === "" || name === "") {
       return null;
     }
     const updatedPath = this.updatePath(path6, classPathPrefix, method, useMap, currentFilePath, currentClass);
     const updatedName = this.updateName(name, classNamePrefix, method, useMap, currentFilePath, currentClass);
     const resolvedIsDynamic = isDynamic || updatedPath.includes("{");
-    const decoratorArgs = decorator.getArguments().map((a) => a.compilerNode);
     const requestMethods = this.middlewareReader.updateRequestMethods(
-      this.middlewareReader.extractInlineRequestMethods(decoratorArgs, useMap, currentFilePath, currentClass),
+      this.middlewareReader.extractObjectRequestMethods(obj, useMap, currentFilePath, currentClass),
       method,
       useMap,
       currentFilePath,
@@ -245064,27 +245259,54 @@ var HttpRouteAttributeReader = class extends RouteAttributeReader {
       useMap,
       currentFilePath,
       currentClass,
-      this.extractClassListArgFromDecorator(decorator, 5, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 6, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 7, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 8, useMap, currentFilePath, currentClass),
-      this.extractClassListArgFromDecorator(decorator, 9, useMap, currentFilePath, currentClass)
+      this.getObjectClassListProp(obj, "middleware", useMap, currentFilePath, currentClass)
     );
     return new HttpRouteData(
       updatedPath,
       updatedName,
-      this.updateHandler(method, useMap, currentFilePath, currentClass),
+      this.resolveHandler(obj, method, useMap, currentFilePath, currentClass),
       requestMethods,
       routeMatchedMiddleware,
       routeDispatchedMiddleware,
       throwableCaughtMiddleware,
       sendingResponseMiddleware,
       responseSentMiddleware,
-      this.middlewareReader.updateRequestStruct(method, useMap, currentFilePath, currentClass),
-      this.middlewareReader.updateResponseStruct(method, useMap, currentFilePath, currentClass),
+      this.resolveRequestStruct(obj, method, useMap, currentFilePath, currentClass),
+      this.resolveResponseStruct(obj, method, useMap, currentFilePath, currentClass),
       resolvedIsDynamic,
-      resolvedIsDynamic ? this.updateParameters(decoratorArgs, method, useMap, currentFilePath, currentClass) : []
+      resolvedIsDynamic ? this.parameterReader.updateParameters(obj, useMap, currentFilePath, currentClass) : []
+    );
+  }
+  resolveHandler(obj, method, useMap, currentFilePath, currentClass) {
+    const fromObj = this.getObjectHandlerProp(obj, "handler", useMap, currentFilePath, currentClass);
+    if (fromObj !== void 0) {
+      return fromObj;
+    }
+    return this.updateHandler(method, useMap, currentFilePath, currentClass);
+  }
+  resolveRequestStruct(obj, method, useMap, currentFilePath, currentClass) {
+    const value = this.extractExprValue(
+      this.getObjectProp(obj, "requestStruct"),
+      useMap,
+      currentFilePath,
+      currentClass
     );
+    if (typeof value === "string" && value !== "") {
+      return value;
+    }
+    return this.middlewareReader.updateRequestStruct(method, useMap, currentFilePath, currentClass);
+  }
+  resolveResponseStruct(obj, method, useMap, currentFilePath, currentClass) {
+    const value = this.extractExprValue(
+      this.getObjectProp(obj, "responseStruct"),
+      useMap,
+      currentFilePath,
+      currentClass
+    );
+    if (typeof value === "string" && value !== "") {
+      return value;
+    }
+    return this.middlewareReader.updateResponseStruct(method, useMap, currentFilePath, currentClass);
   }
   updatePath(path6, classPathPrefix, method, useMap, currentFilePath, currentClass) {
     if (classPathPrefix !== "") {
@@ -245120,26 +245342,59 @@ var HttpRouteAttributeReader = class extends RouteAttributeReader {
     }
     return name;
   }
+  /**
+   * Emit `new DynamicRoute(path, name, regex, parameters, handler,
+   * requestMethods, ...5 middleware, requestStruct, responseStruct)` or
+   * `new Route(path, name, handler, requestMethods, ...5 middleware,
+   * requestStruct, responseStruct)`, matching the framework constructor order.
+   *
+   * For dynamic routes the regex slot is emitted as an empty-string
+   * placeholder; the generator computes and injects the real regex (it owns
+   * the routing `Processor`), and the parameters array is always emitted (`[]`
+   * when empty).
+   */
   buildRouteExpr(data) {
     const args = [this.buildEnumCaseExpr(data.path), this.buildEnumCaseExpr(data.name)];
-    if (data.isDynamic && data.parameters.length > 0) {
+    if (data.isDynamic) {
+      args.push(this.buildStringExpr(""));
       args.push(this.parameterReader.buildParameterListExpr([...data.parameters]));
     }
-    if (data.handler !== null) {
-      args.push(this.buildHandlerExpr(data.handler));
-    } else {
-      args.push(this.buildNullExpr());
-    }
-    if (data.requestMethods.length > 0) {
-      args.push(this.buildEnumCaseArrayExpr(data.requestMethods));
-    }
+    args.push(data.handler !== null ? this.buildHandlerExpr(data.handler) : this.buildNullExpr());
+    args.push(this.buildEnumCaseArrayExpr(data.requestMethods));
     args.push(...this.middlewareReader.buildRouteMiddlewareArgs(data));
     args.push(...this.middlewareReader.buildRouteStructArgs(data));
     const targetClass = data.isDynamic ? "Valkyrja\\Http\\Routing\\Data\\DynamicRoute" : "Valkyrja\\Http\\Routing\\Data\\Route";
     return this.buildNewExpr(targetClass, args);
   }
-  updateParameters(decoratorArgs, method, useMap, currentFilePath, currentClass) {
-    return this.parameterReader.updateParameters(decoratorArgs, method, useMap, currentFilePath, currentClass);
+  /**
+   * Build the class-name → absolute-file-path map for every handler and
+   * middleware class the generated data cache references, so the generator can
+   * emit the matching import statements.
+   */
+  buildImportMap(routeData, useMap, currentFilePath, currentClass) {
+    const importMap = {};
+    for (const data of Object.values(routeData)) {
+      if (data.handler !== null) {
+        this.addClassImport(importMap, data.handler.class, useMap, currentFilePath, currentClass);
+      }
+      for (const middleware of [
+        ...data.routeMatchedMiddleware,
+        ...data.routeDispatchedMiddleware,
+        ...data.throwableCaughtMiddleware,
+        ...data.sendingResponseMiddleware,
+        ...data.responseSentMiddleware
+      ]) {
+        this.addClassImport(importMap, middleware, useMap, currentFilePath, currentClass);
+      }
+    }
+    return importMap;
+  }
+  addClassImport(importMap, className, useMap, currentFilePath, currentClass) {
+    const shortName = className.slice(className.lastIndexOf("\\") + 1);
+    const filePath = shortName === currentClass ? currentFilePath : this.resolveImportToFilePath(shortName, useMap, currentFilePath);
+    if (filePath !== "") {
+      importMap[shortName] = filePath;
+    }
   }
 };
 
@@ -245272,7 +245527,7 @@ var ListenerProviderReader = class _ListenerProviderReader extends AstReader {
 };
 
 // src/Sindri/Ast/RouteProviderReader.ts
-var import_ts_morph8 = __toESM(require_ts_morph(), 1);
+var import_ts_morph7 = __toESM(require_ts_morph(), 1);
 
 // src/Sindri/Ast/Data/Result/RouteProviderResult.ts
 var RouteProviderResult = class _RouteProviderResult {
@@ -245356,12 +245611,12 @@ var RouteProviderReader = class _RouteProviderReader extends AstReader {
     if (array === void 0) {
       return [];
     }
-    return array.elements.filter((element) => import_ts_morph8.ts.isNewExpression(element));
+    return array.elements.filter((element) => import_ts_morph7.ts.isNewExpression(element));
   }
 };
 
 // src/Sindri/Ast/ServiceProviderReader.ts
-var import_ts_morph9 = __toESM(require_ts_morph(), 1);
+var import_ts_morph8 = __toESM(require_ts_morph(), 1);
 
 // src/Sindri/Ast/Data/Result/ServiceProviderResult.ts
 var ServiceProviderResult = class _ServiceProviderResult {
@@ -245414,7 +245669,7 @@ var ServiceProviderReader = class _ServiceProviderReader extends AstReader {
     }
     const map = {};
     for (const prop of obj.properties) {
-      if (!import_ts_morph9.ts.isPropertyAssignment(prop)) {
+      if (!import_ts_morph8.ts.isPropertyAssignment(prop)) {
         continue;
       }
       const serviceId = this.resolvePropertyKeyToString(prop.name, useMap, filePath);
@@ -245435,8 +245690,8 @@ var ServiceProviderReader = class _ServiceProviderReader extends AstReader {
    * Handles: `ProviderClass.publishMethod` and `[ProviderClass, 'method']`.
    */
   extractHandlerFromValue(node, useMap, filePath, currentClass) {
-    if (import_ts_morph9.ts.isPropertyAccessExpression(node)) {
-      const className = import_ts_morph9.ts.isIdentifier(node.expression) ? node.expression.text : void 0;
+    if (import_ts_morph8.ts.isPropertyAccessExpression(node)) {
+      const className = import_ts_morph8.ts.isIdentifier(node.expression) ? node.expression.text : void 0;
       if (className === void 0) {
         return void 0;
       }
@@ -245444,7 +245699,7 @@ var ServiceProviderReader = class _ServiceProviderReader extends AstReader {
       const resolvedClass = className === "self" || className === "this" ? currentClass : className;
       return [resolvedClass, methodName];
     }
-    if (import_ts_morph9.ts.isArrayLiteralExpression(node) && node.elements.length === 2) {
+    if (import_ts_morph8.ts.isArrayLiteralExpression(node) && node.elements.length === 2) {
       const raw = this.extractHandlerFromTsArray(node, useMap, filePath, currentClass);
       if (raw !== void 0) {
         return [raw.class, raw.method];
@@ -245455,7 +245710,7 @@ var ServiceProviderReader = class _ServiceProviderReader extends AstReader {
 };
 
 // src/Sindri/Generator/Ast/Cli/AstCliDataFileGenerator.ts
-var import_ts_morph10 = __toESM(require_ts_morph(), 1);
+var import_ts_morph9 = __toESM(require_ts_morph(), 1);
 var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGenerator {
   /** The framework classes every generated CLI data file imports as values. */
   static FRAMEWORK_IMPORTS = {
@@ -245473,13 +245728,13 @@ var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGene
     RouteContract: "@valkyrjaio/valkyrja/Cli/Routing/Data/Contract/RouteContract.ts"
   };
   classImportMap = {};
-  printer = import_ts_morph10.ts.createPrinter({ newLine: import_ts_morph10.ts.NewLineKind.LineFeed });
-  dummySourceFile = import_ts_morph10.ts.createSourceFile(
+  printer = import_ts_morph9.ts.createPrinter({ newLine: import_ts_morph9.ts.NewLineKind.LineFeed });
+  dummySourceFile = import_ts_morph9.ts.createSourceFile(
     "_dummy.ts",
     "",
-    import_ts_morph10.ts.ScriptTarget.ESNext,
+    import_ts_morph9.ts.ScriptTarget.ESNext,
     false,
-    import_ts_morph10.ts.ScriptKind.TS
+    import_ts_morph9.ts.ScriptKind.TS
   );
   generateFile(directory, className, namespace, routes) {
     const userImportsBlock = this.buildUserImportsBlock(this.classImportMap, [
@@ -245508,18 +245763,27 @@ var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGene
    * its command name (the first constructor argument) and emitted verbatim.
    */
   generateFileFromRoutes(directory, className, namespace, routeExprs) {
-    const routes = {};
+    return this.generateMergedFile(directory, className, namespace, {}, routeExprs);
+  }
+  /**
+   * Generate the CLI routing data file by MERGING attribute-scanned command
+   * routes with imperative `getRoutes()` route objects — both are keyed by
+   * command name into a single routes map. Attribute entries come first;
+   * imperative entries override on a name collision.
+   */
+  generateMergedFile(directory, className, namespace, routes, routeExprs) {
+    const merged = { ...routes };
     for (const expr of routeExprs) {
-      if (!import_ts_morph10.ts.isNewExpression(expr)) {
+      if (!import_ts_morph9.ts.isNewExpression(expr)) {
         continue;
       }
       const key = this.routeKey((expr.arguments ?? [])[0]);
       if (key === void 0) {
         continue;
       }
-      routes[key] = expr;
+      merged[key] = expr;
     }
-    return this.generateFile(directory, className, namespace, routes);
+    return this.generateFile(directory, className, namespace, merged);
   }
   /**
    * Derive the map key for a route from its name argument.
@@ -245534,10 +245798,10 @@ var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGene
     if (nameArg === void 0) {
       return void 0;
     }
-    if (import_ts_morph10.ts.isStringLiteral(nameArg)) {
+    if (import_ts_morph9.ts.isStringLiteral(nameArg)) {
       return nameArg.text;
     }
-    if (import_ts_morph10.ts.isPropertyAccessExpression(nameArg) && import_ts_morph10.ts.isIdentifier(nameArg.expression)) {
+    if (import_ts_morph9.ts.isPropertyAccessExpression(nameArg) && import_ts_morph9.ts.isIdentifier(nameArg.expression)) {
       return `${nameArg.expression.text}::${nameArg.name.text}`;
     }
     return void 0;
@@ -245550,7 +245814,7 @@ var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGene
     const lines = [];
     for (const [key, valueExpr] of entries) {
       const printedValue = this.printExpr(valueExpr);
-      const formattedKey = key.includes("::") ? `[${this.printer.printNode(import_ts_morph10.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(key), this.dummySourceFile)}]` : `['${key}']`;
+      const formattedKey = key.includes("::") ? `[${this.printer.printNode(import_ts_morph9.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(key), this.dummySourceFile)}]` : `['${key}']`;
       lines.push(`            ${formattedKey}: (): RouteContract => ${printedValue},`);
     }
     return ["super({", ...lines, "        });"].join("\n        ");
@@ -245561,12 +245825,12 @@ var AstCliDataFileGenerator = class _AstCliDataFileGenerator extends AstFileGene
    * carry no source positions) are emitted through the printer.
    */
   printExpr(expr) {
-    return expr.pos >= 0 ? expr.getText() : this.printer.printNode(import_ts_morph10.ts.EmitHint.Unspecified, expr, this.dummySourceFile);
+    return expr.pos >= 0 ? expr.getText() : this.printer.printNode(import_ts_morph9.ts.EmitHint.Unspecified, expr, this.dummySourceFile);
   }
 };
 
 // src/Sindri/Generator/Ast/Container/AstContainerDataFileGenerator.ts
-var import_ts_morph11 = __toESM(require_ts_morph(), 1);
+var import_ts_morph10 = __toESM(require_ts_morph(), 1);
 var AstContainerDataFileGenerator = class _AstContainerDataFileGenerator extends AstFileGenerator {
   /** The framework class every generated container data file imports as a value. */
   static FRAMEWORK_IMPORTS = {
@@ -245577,13 +245841,13 @@ var AstContainerDataFileGenerator = class _AstContainerDataFileGenerator extends
     ContainerContract: "@valkyrjaio/valkyrja/Container/Manager/Contract/ContainerContract.ts"
   };
   classImportMap = {};
-  printer = import_ts_morph11.ts.createPrinter({ newLine: import_ts_morph11.ts.NewLineKind.LineFeed });
-  dummySourceFile = import_ts_morph11.ts.createSourceFile(
+  printer = import_ts_morph10.ts.createPrinter({ newLine: import_ts_morph10.ts.NewLineKind.LineFeed });
+  dummySourceFile = import_ts_morph10.ts.createSourceFile(
     "_dummy.ts",
     "",
-    import_ts_morph11.ts.ScriptTarget.ESNext,
+    import_ts_morph10.ts.ScriptTarget.ESNext,
     false,
-    import_ts_morph11.ts.ScriptKind.TS
+    import_ts_morph10.ts.ScriptKind.TS
   );
   generateFile(directory, className, namespace, publishers) {
     const userImportsBlock = this.buildUserImportsBlock(this.classImportMap, [
@@ -245614,7 +245878,7 @@ var AstContainerDataFileGenerator = class _AstContainerDataFileGenerator extends
     const lines = [];
     for (const [serviceId, [providerClass, methodName]] of entries) {
       const shortProviderClass = providerClass.slice(providerClass.lastIndexOf("\\") + 1);
-      const formattedKey = serviceId.includes("::") ? `[${this.printer.printNode(import_ts_morph11.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(serviceId), this.dummySourceFile)}]` : `['${serviceId}']`;
+      const formattedKey = serviceId.includes("::") ? `[${this.printer.printNode(import_ts_morph10.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(serviceId), this.dummySourceFile)}]` : `['${serviceId}']`;
       lines.push(
         `            ${formattedKey}: (container: ContainerContract) => ${shortProviderClass}.${methodName}(container),`
       );
@@ -245626,7 +245890,7 @@ var AstContainerDataFileGenerator = class _AstContainerDataFileGenerator extends
 };
 
 // src/Sindri/Generator/Ast/Event/AstEventDataFileGenerator.ts
-var import_ts_morph12 = __toESM(require_ts_morph(), 1);
+var import_ts_morph11 = __toESM(require_ts_morph(), 1);
 var AstEventDataFileGenerator = class _AstEventDataFileGenerator extends AstFileGenerator {
   /** The framework class every generated event data file imports as a value. */
   static FRAMEWORK_IMPORTS = {
@@ -245641,13 +245905,13 @@ var AstEventDataFileGenerator = class _AstEventDataFileGenerator extends AstFile
     ListenerContract: "@valkyrjaio/valkyrja/Event/Data/Contract/ListenerContract.ts"
   };
   classImportMap = {};
-  printer = import_ts_morph12.ts.createPrinter({ newLine: import_ts_morph12.ts.NewLineKind.LineFeed });
-  dummySourceFile = import_ts_morph12.ts.createSourceFile(
+  printer = import_ts_morph11.ts.createPrinter({ newLine: import_ts_morph11.ts.NewLineKind.LineFeed });
+  dummySourceFile = import_ts_morph11.ts.createSourceFile(
     "_dummy.ts",
     "",
-    import_ts_morph12.ts.ScriptTarget.ESNext,
+    import_ts_morph11.ts.ScriptTarget.ESNext,
     false,
-    import_ts_morph12.ts.ScriptKind.TS
+    import_ts_morph11.ts.ScriptKind.TS
   );
   generateFile(directory, className, namespace, listeners) {
     const userImportsBlock = this.buildUserImportsBlock(this.classImportMap, [
@@ -245682,7 +245946,7 @@ var AstEventDataFileGenerator = class _AstEventDataFileGenerator extends AstFile
     }
     const lines = [];
     for (const [key, valueExpr] of entries) {
-      const printed = this.printer.printNode(import_ts_morph12.ts.EmitHint.Unspecified, valueExpr, this.dummySourceFile);
+      const printed = this.printer.printNode(import_ts_morph11.ts.EmitHint.Unspecified, valueExpr, this.dummySourceFile);
       lines.push(`            ['${key}']: (): ListenerContract => ${printed},`);
     }
     return ["super(", "            {},", "            {", ...lines, "            },", "        );"].join(
@@ -245692,7 +245956,7 @@ var AstEventDataFileGenerator = class _AstEventDataFileGenerator extends AstFile
 };
 
 // src/Sindri/Generator/Ast/Http/AstHttpDataFileGenerator.ts
-var import_ts_morph13 = __toESM(require_ts_morph(), 1);
+var import_ts_morph12 = __toESM(require_ts_morph(), 1);
 
 // node_modules/@valkyrjaio/valkyrja/src/Valkyrja/Http/Message/Enum/RequestMethod.ts
 function allRequestMethods() {
@@ -246064,6 +246328,8 @@ var Regex = class _Regex {
   static ALPHA_UPPERCASE = "[A-Z]+";
   static ALPHA_NUM = "[a-zA-Z0-9]+";
   static ALPHA_NUM_UNDERSCORE = "\\w+";
+  // Anchors only — JavaScript's `RegExp` constructor takes a bare pattern, so
+  // PHP-style `/.../` delimiters would be matched as literal characters.
   static START = "^";
   static END = "$";
   static START_CAPTURE_GROUP = "(";
@@ -246173,29 +246439,20 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
   };
   classImportMap = {};
   processor;
-  printer = import_ts_morph13.ts.createPrinter({ newLine: import_ts_morph13.ts.NewLineKind.LineFeed });
-  dummySourceFile = import_ts_morph13.ts.createSourceFile(
+  printer = import_ts_morph12.ts.createPrinter({ newLine: import_ts_morph12.ts.NewLineKind.LineFeed });
+  dummySourceFile = import_ts_morph12.ts.createSourceFile(
     "_dummy.ts",
     "",
-    import_ts_morph13.ts.ScriptTarget.ESNext,
+    import_ts_morph12.ts.ScriptTarget.ESNext,
     false,
-    import_ts_morph13.ts.ScriptKind.TS
+    import_ts_morph12.ts.ScriptKind.TS
   );
   constructor(processor = new Processor()) {
     super();
     this.processor = processor;
   }
   generateFile(directory, className, namespace, routes, routeData) {
-    const userImportsBlock = this.buildUserImportsBlock(this.classImportMap, [
-      ...Object.keys(_AstHttpDataFileGenerator.FRAMEWORK_IMPORTS),
-      ...Object.keys(_AstHttpDataFileGenerator.FRAMEWORK_TYPE_IMPORTS)
-    ]);
-    const routesContent = this.getRoutesAsContent(routes, routeData);
-    const paths = this.printNestedObject(this.buildPaths(routeData));
-    const dynamicPaths = this.printNestedObject(this.buildDynamicPaths(routeData));
-    const regexes = this.printNestedObject(this.buildRegexes(routeData));
-    const data = this.assembleFile(className, userImportsBlock, routesContent, paths, dynamicPaths, regexes);
-    return this.writeFile(directory, className, data);
+    return this.generateMergedFile(directory, className, namespace, routes, routeData, []);
   }
   /**
    * Generate the routing data file from imperative `getRoutes()` route
@@ -246206,19 +246463,45 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
    * own arguments, mirroring the framework's runtime `RouteCollection`
    * (literal path and regex, request methods defaulting to `[HEAD, GET]`).
    */
-  generateFileFromRoutes(directory, className, _namespace, routeExprs) {
+  generateFileFromRoutes(directory, className, namespace, routeExprs) {
+    return this.generateMergedFile(directory, className, namespace, {}, {}, routeExprs);
+  }
+  /**
+   * Generate the routing data file by MERGING attribute-scanned routes with
+   * imperative `getRoutes()` route objects — the four lookup maps (routes,
+   * paths, dynamicPaths, regexes) are built from both sources and combined.
+   * Attribute entries are emitted first, then imperative ones.
+   */
+  generateMergedFile(directory, className, _namespace, routes, routeData, routeExprs) {
     const userImportsBlock = this.buildUserImportsBlock(this.classImportMap, [
       ...Object.keys(_AstHttpDataFileGenerator.FRAMEWORK_IMPORTS),
       ...Object.keys(_AstHttpDataFileGenerator.FRAMEWORK_TYPE_IMPORTS)
     ]);
     const metas = routeExprs.map((expr) => this.extractRouteMeta(expr)).filter((meta) => meta !== void 0);
-    const routesContent = this.getImperativeRoutesContent(metas);
-    const paths = this.printNestedObject(this.buildImperativePaths(metas, false));
-    const dynamicPaths = this.printNestedObject(this.buildImperativePaths(metas, true));
-    const regexes = this.printNestedObject(this.buildImperativeRegexes(metas));
+    const routesContent = this.wrapRoutes([
+      ...this.getRouteLines(routes, routeData),
+      ...this.getImperativeRouteLines(metas)
+    ]);
+    const paths = this.printNestedObject(
+      this.mergeNested(this.buildPaths(routeData), this.buildImperativePaths(metas, false))
+    );
+    const dynamicPaths = this.printNestedObject(
+      this.mergeNested(this.buildDynamicPaths(routeData), this.buildImperativePaths(metas, true))
+    );
+    const regexes = this.printNestedObject(
+      this.mergeNested(this.buildRegexes(routeData), this.buildImperativeRegexes(metas))
+    );
     const data = this.assembleFile(className, userImportsBlock, routesContent, paths, dynamicPaths, regexes);
     return this.writeFile(directory, className, data);
   }
+  /** Deep-merge two `method → key → name` maps; entries in `b` override `a`. */
+  mergeNested(a, b) {
+    const merged = {};
+    for (const [outerKey, innerMap] of [...Object.entries(a), ...Object.entries(b)]) {
+      merged[outerKey] = { ...merged[outerKey] ?? {}, ...innerMap };
+    }
+    return merged;
+  }
   assembleFile(className, userImportsBlock, routesContent, paths, dynamicPaths, regexes) {
     return [
       "// This file was automatically generated by Sindri.",
@@ -246310,24 +246593,24 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
       const innerProps = [];
       for (const [innerKey, value] of Object.entries(innerMap)) {
         innerProps.push(
-          import_ts_morph13.ts.factory.createPropertyAssignment(
-            import_ts_morph13.ts.factory.createStringLiteral(innerKey),
-            import_ts_morph13.ts.factory.createStringLiteral(value)
+          import_ts_morph12.ts.factory.createPropertyAssignment(
+            import_ts_morph12.ts.factory.createStringLiteral(innerKey),
+            import_ts_morph12.ts.factory.createStringLiteral(value)
           )
         );
       }
       outerProps.push(
-        import_ts_morph13.ts.factory.createPropertyAssignment(
-          import_ts_morph13.ts.factory.createStringLiteral(outerKey),
-          import_ts_morph13.ts.factory.createObjectLiteralExpression(innerProps, true)
+        import_ts_morph12.ts.factory.createPropertyAssignment(
+          import_ts_morph12.ts.factory.createStringLiteral(outerKey),
+          import_ts_morph12.ts.factory.createObjectLiteralExpression(innerProps, true)
         )
       );
     }
-    return import_ts_morph13.ts.factory.createObjectLiteralExpression(outerProps, true);
+    return import_ts_morph12.ts.factory.createObjectLiteralExpression(outerProps, true);
   }
   printNestedObject(data) {
     return this.printer.printNode(
-      import_ts_morph13.ts.EmitHint.Unspecified,
+      import_ts_morph12.ts.EmitHint.Unspecified,
       this.buildNestedStringArrayExpr(data),
       this.dummySourceFile
     );
@@ -246378,24 +246661,41 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
     return methods;
   }
   getRoutesAsContent(routes, routeData) {
-    const entries = Object.entries(routes);
-    if (entries.length === 0) {
+    return this.wrapRoutes(this.getRouteLines(routes, routeData));
+  }
+  /** Wrap route closure lines in the `{ ... }` object-literal body (or `{}`). */
+  wrapRoutes(lines) {
+    if (lines.length === 0) {
       return "{}";
     }
+    return ["{", ...lines, "        }"].join("\n        ");
+  }
+  /** Build the per-route closure lines for attribute-scanned routes. */
+  getRouteLines(routes, routeData) {
     const lines = [];
-    for (const [key, routeExpr] of entries) {
+    for (const [key, routeExpr] of Object.entries(routes)) {
       const data = routeData[key] ?? null;
-      let expr = routeExpr;
-      if (data !== null && data.isDynamic && import_ts_morph13.ts.isNewExpression(expr)) {
-        const computedRegex = data.parameters.length > 0 ? this.computeRegex(data) : "";
-        const args = [...expr.arguments ?? [], import_ts_morph13.ts.factory.createStringLiteral(computedRegex)];
-        expr = import_ts_morph13.ts.factory.createNewExpression(expr.expression, expr.typeArguments, args);
-      }
-      const printedRoute = this.printer.printNode(import_ts_morph13.ts.EmitHint.Unspecified, expr, this.dummySourceFile);
-      const formattedKey = key.includes("::") ? `[${this.printer.printNode(import_ts_morph13.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(key), this.dummySourceFile)}]` : `['${key}']`;
+      const expr = data !== null ? this.injectRegex(routeExpr, data) : routeExpr;
+      const printedRoute = this.printer.printNode(import_ts_morph12.ts.EmitHint.Unspecified, expr, this.dummySourceFile);
+      const formattedKey = key.includes("::") ? `[${this.printer.printNode(import_ts_morph12.ts.EmitHint.Unspecified, this.buildEnumCaseExpr(key), this.dummySourceFile)}]` : `['${key}']`;
       lines.push(`            ${formattedKey}: (): RouteContract => ${printedRoute},`);
     }
-    return ["{", ...lines, "        }"].join("\n        ");
+    return lines;
+  }
+  /**
+   * Replace the regex argument (slot 2) of a dynamic `new DynamicRoute(...)`
+   * expression with the regex computed from the route's parameters. The reader
+   * emits an empty-string placeholder there; the generator owns the routing
+   * `Processor` and computes the real value here.
+   */
+  injectRegex(expr, data) {
+    if (!(data.isDynamic && import_ts_morph12.ts.isNewExpression(expr))) {
+      return expr;
+    }
+    const computedRegex = data.parameters.length > 0 ? this.computeRegex(data) : "";
+    const original = expr.arguments ?? import_ts_morph12.ts.factory.createNodeArray();
+    const args = original.map((arg, index) => index === 2 ? import_ts_morph12.ts.factory.createStringLiteral(computedRegex) : arg);
+    return import_ts_morph12.ts.factory.createNewExpression(expr.expression, expr.typeArguments, args);
   }
   // -------------------------------------------------------------------------
   // Imperative `getRoutes()` support
@@ -246407,11 +246707,11 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
    *   DynamicRoute(path, name, regex, parameters, handler, requestMethods?)
    */
   extractRouteMeta(expr) {
-    if (!import_ts_morph13.ts.isNewExpression(expr) || !import_ts_morph13.ts.isIdentifier(expr.expression)) {
+    if (!import_ts_morph12.ts.isNewExpression(expr) || !import_ts_morph12.ts.isIdentifier(expr.expression)) {
       return void 0;
     }
     const isDynamic = expr.expression.text === "DynamicRoute";
-    const args = expr.arguments ?? import_ts_morph13.ts.factory.createNodeArray();
+    const args = expr.arguments ?? import_ts_morph12.ts.factory.createNodeArray();
     const path6 = this.stringArg(args[0]);
     const name = this.stringArg(args[1]);
     if (name === void 0 || path6 === void 0) {
@@ -246423,7 +246723,7 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
     return { expr, name, path: path6, isDynamic, regex, methods };
   }
   stringArg(node) {
-    return node !== void 0 && import_ts_morph13.ts.isStringLiteral(node) ? node.text : void 0;
+    return node !== void 0 && import_ts_morph12.ts.isStringLiteral(node) ? node.text : void 0;
   }
   /**
    * Resolve a `[RequestMethod.GET, ...]` argument to method-name strings,
@@ -246431,12 +246731,12 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
    * and expanding `RequestMethod.ANY` to every request method.
    */
   extractMethodNamesFromArg(node) {
-    if (node === void 0 || !import_ts_morph13.ts.isArrayLiteralExpression(node)) {
+    if (node === void 0 || !import_ts_morph12.ts.isArrayLiteralExpression(node)) {
       return ["HEAD" /* HEAD */, "GET" /* GET */];
     }
     const methods = [];
     for (const element of node.elements) {
-      if (!import_ts_morph13.ts.isPropertyAccessExpression(element)) {
+      if (!import_ts_morph12.ts.isPropertyAccessExpression(element)) {
         continue;
       }
       const method = element.name.text;
@@ -246447,15 +246747,9 @@ var AstHttpDataFileGenerator = class _AstHttpDataFileGenerator extends AstFileGe
     }
     return methods;
   }
-  getImperativeRoutesContent(metas) {
-    if (metas.length === 0) {
-      return "{}";
-    }
-    const lines = [];
-    for (const meta of metas) {
-      lines.push(`            ['${meta.name}']: (): RouteContract => ${meta.expr.getText()},`);
-    }
-    return ["{", ...lines, "        }"].join("\n        ");
+  /** Build the per-route closure lines for imperative `getRoutes()` routes. */
+  getImperativeRouteLines(metas) {
+    return metas.map((meta) => `            ['${meta.name}']: (): RouteContract => ${meta.expr.getText()},`);
   }
   buildImperativePaths(metas, dynamic) {
     const paths = {};
@@ -246698,15 +246992,17 @@ var GenerateDataFromAst = class extends GenerateFromAst {
         }
         const attrResult = this.cliRouteAttributeReader.readFile(controllerPath);
         Object.assign(allRoutes, attrResult.routes);
+        this.mergeReaderImports(importMap, attrResult.importMap, config);
       }
     }
     this.cliGenerator.classImportMap = importMap;
-    const status = imperativeRoutes.length > 0 ? this.cliGenerator.generateFileFromRoutes(
+    const status = this.cliGenerator.generateMergedFile(
       config.dataPath,
       "AppCliRoutingData",
       config.dataNamespace,
+      allRoutes,
       imperativeRoutes
-    ) : this.cliGenerator.generateFile(config.dataPath, "AppCliRoutingData", config.dataNamespace, allRoutes);
+    );
     return this.addMessagesForGenerateStatus(output, status).withAddedMessages(new NewLine()).writeMessages();
   }
   generateHttpData(httpRouteProviders, config, output) {
@@ -246736,23 +247032,33 @@ var GenerateDataFromAst = class extends GenerateFromAst {
         const attrResult = this.httpRouteAttributeReader.readFile(controllerPath);
         Object.assign(allRoutes, attrResult.routes);
         Object.assign(allRouteData, attrResult.routeData);
+        this.mergeReaderImports(importMap, attrResult.importMap, config);
       }
     }
     this.httpGenerator.classImportMap = importMap;
-    const status = imperativeRoutes.length > 0 ? this.httpGenerator.generateFileFromRoutes(
-      config.dataPath,
-      "AppHttpRoutingData",
-      config.dataNamespace,
-      imperativeRoutes
-    ) : this.httpGenerator.generateFile(
+    const status = this.httpGenerator.generateMergedFile(
       config.dataPath,
       "AppHttpRoutingData",
       config.dataNamespace,
       allRoutes,
-      allRouteData
+      allRouteData,
+      imperativeRoutes
     );
     return this.addMessagesForGenerateStatus(output, status).withAddedMessages(new NewLine()).writeMessages();
   }
+  /**
+   * Merge the class-name → absolute-file-path imports a route attribute reader
+   * resolved (handler/help-text/middleware classes) into the generated data
+   * file's import map, converting each absolute path to the specifier the
+   * generated file imports it by — relative to the output directory for
+   * application source, or the owning package's own specifier for a class an
+   * installed package exposes.
+   */
+  mergeReaderImports(importMap, readerImportMap, config) {
+    for (const [name, absolutePath] of Object.entries(readerImportMap)) {
+      importMap[name] = this.importSpecifier(config.dataPath, absolutePath);
+    }
+  }
   addMessagesForGenerateStatus(output, status) {
     let text = "Failed";
     let formatter = new ErrorFormatter();