@valkyrjaio/valkyrja 26.5.0 → 26.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/valkyrja",
-    "version": "26.5.0",
+    "version": "26.6.0",
     "description": "The Valkyrja Framework.",
     "keywords": [
         "framework",

package/src/Valkyrja/Application/Constant/ApplicationInfo.ts

@@ -8,8 +8,8 @@
  */
 
 export class ApplicationInfo {
-    static readonly VERSION = '26.5.0' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'July 31 2026 08:59:22 MST' as const;
+    static readonly VERSION = '26.6.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'August 1 2026 18:07:10 MST' as const;
     static readonly ASCII = `
                  _ _               _
      /\\   /\\__ _| | | ___   _ _ __(_) __ _

package/src/Valkyrja/Cli/Routing/Attribute/ArgumentParameter.ts

@@ -0,0 +1,23 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ensureCliRouteMethodMetadata } from './RouteAttributeMetadata.ts';
+
+import type { ArgumentParameterOptions } from './RouteOptions.ts';
+
+/**
+ * Declare a command argument on a controller method.
+ *
+ * Mirrors PHP's repeatable `#[ArgumentParameter]`.
+ */
+export function ArgumentParameter(options: ArgumentParameterOptions) {
+    return function (_value: unknown, context: ClassMethodDecoratorContext): void {
+        ensureCliRouteMethodMetadata(context.metadata, context.name).arguments.push(options);
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/OptionParameter.ts

@@ -0,0 +1,23 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ensureCliRouteMethodMetadata } from './RouteAttributeMetadata.ts';
+
+import type { OptionParameterOptions } from './RouteOptions.ts';
+
+/**
+ * Declare a command option on a controller method.
+ *
+ * Mirrors PHP's repeatable `#[OptionParameter]`.
+ */
+export function OptionParameter(options: OptionParameterOptions) {
+    return function (_value: unknown, context: ClassMethodDecoratorContext): void {
+        ensureCliRouteMethodMetadata(context.metadata, context.name).options.push(options);
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/Route/Middleware.ts

@@ -0,0 +1,24 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ensureCliRouteMethodMetadata } from '../RouteAttributeMetadata.ts';
+
+import type { CliMiddlewareReference } from '../RouteAttributeMetadata.ts';
+
+/**
+ * Add a middleware to the command(s) declared on a controller method.
+ *
+ * Mirrors PHP's repeatable `#[Middleware]`. The collector routes the class into
+ * whichever middleware buckets it satisfies.
+ */
+export function Middleware(middleware: CliMiddlewareReference) {
+    return function (_value: unknown, context: ClassMethodDecoratorContext): void {
+        ensureCliRouteMethodMetadata(context.metadata, context.name).middleware.push(middleware);
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/Route/Name.ts

@@ -0,0 +1,29 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ensureCliRouteMetadata, ensureCliRouteMethodMetadata } from '../RouteAttributeMetadata.ts';
+
+/**
+ * Add a name segment to a command.
+ *
+ * Mirrors PHP's `#[Name]` (targets a class or a method): a class-level name
+ * prefixes every command in the controller, a method-level name is appended to
+ * that method's command names.
+ */
+export function Name(value: string) {
+    return function (_value: unknown, context: ClassDecoratorContext | ClassMethodDecoratorContext): void {
+        if (context.kind === 'class') {
+            ensureCliRouteMetadata(context.metadata).classNames.push(value);
+
+            return;
+        }
+
+        ensureCliRouteMethodMetadata(context.metadata, context.name).names.push(value);
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/Route/RouteHandler.ts

@@ -0,0 +1,30 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { ensureCliRouteMethodMetadata } from '../RouteAttributeMetadata.ts';
+
+import type { CliHandlerReference } from '../RouteAttributeMetadata.ts';
+
+/**
+ * Assign the handler for the command(s) declared on a controller method.
+ *
+ * Mirrors PHP's `#[RouteHandler([CliRouteProvider::class, 'testCommandHandler'])]`,
+ * written here as `@RouteHandler([() => CliRouteProvider, 'testCommandHandler'])`.
+ *
+ * The two pieces of that shape solve two independent problems (see
+ * `CliHandlerReference`): the **thunk** keeps the class binding untouched at
+ * decoration time so a circular or self-referential import cannot trip the
+ * temporal dead zone, and the generic **`THandler`** makes the method name a
+ * checked key of that class rather than an arbitrary string.
+ */
+export function RouteHandler<THandler>(handler: CliHandlerReference<THandler>) {
+    return function (_value: unknown, context: ClassMethodDecoratorContext): void {
+        ensureCliRouteMethodMetadata(context.metadata, context.name).handler = handler;
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/Route.ts

@@ -0,0 +1,25 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { createCliRouteDefinition, ensureCliRouteMethodMetadata } from './RouteAttributeMetadata.ts';
+
+import type { CliRouteOptions } from './RouteOptions.ts';
+
+/**
+ * Declare a CLI command on a controller method.
+ *
+ * Mirrors PHP's repeatable `#[Route]`: stack it to declare several commands for
+ * one method. Sindri reads it statically to build the command cache; in debug
+ * mode the runtime `AttributeRouteCollector` reads it from the class metadata.
+ */
+export function Route<THandler = unknown, THelpText = unknown>(options: CliRouteOptions<THandler, THelpText>) {
+    return function (_value: unknown, context: ClassMethodDecoratorContext): void {
+        ensureCliRouteMethodMetadata(context.metadata, context.name).routes.push(createCliRouteDefinition(options));
+    };
+}

package/src/Valkyrja/Cli/Routing/Attribute/RouteAttributeMetadata.ts

@@ -0,0 +1,227 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { ContainerContract } from '../../../Container/Manager/Contract/ContainerContract.ts';
+import type { MessageContract } from '../../Interaction/Message/Contract/MessageContract.ts';
+import type { OutputContract } from '../../Interaction/Output/Contract/OutputContract.ts';
+import type { RouteDispatchedMiddlewareContract } from '../../Middleware/Contract/RouteDispatchedMiddlewareContract.ts';
+import type { RouteMatchedMiddlewareContract } from '../../Middleware/Contract/RouteMatchedMiddlewareContract.ts';
+import type { ThrowableCaughtMiddlewareContract } from '../../Middleware/Contract/ThrowableCaughtMiddlewareContract.ts';
+import type { ProcessExitingMiddlewareContract } from '../../Middleware/Contract/ProcessExitingMiddlewareContract.ts';
+import type { RouteContract } from '../Data/Contract/RouteContract.ts';
+import type { ArgumentParameterOptions, CliRouteOptions, OptionParameterOptions } from './RouteOptions.ts';
+
+/**
+ * The signature every CLI command handler must have — the typed closure the
+ * dispatcher invokes (mirrors PHP's `OutputContract` handler contract).
+ */
+export type CliHandler = (container: ContainerContract, route: RouteContract) => OutputContract;
+
+/**
+ * The signature every help-text provider must have.
+ */
+export type CliHelpText = () => MessageContract;
+
+/**
+ * The keys of `T` whose value is a valid `CliHandler`.
+ *
+ * Fix 2 (types) — independent of the thunk below. A bare `string` method name
+ * lets a typo or a wrong-signature method compile and only blow up at run time;
+ * this mapped type turns both into compile errors. Do not relax it to `string`.
+ */
+type CliHandlerKeys<T> = { [K in keyof T]: T[K] extends CliHandler ? K : never }[keyof T];
+
+/**
+ * The keys of `T` whose value returns a `MessageContract` — the help-text
+ * counterpart of `CliHandlerKeys` (Fix 2).
+ */
+type CliHelpTextKeys<T> = { [K in keyof T]: T[K] extends CliHelpText ? K : never }[keyof T];
+
+/**
+ * A command handler reference: a **thunk** returning the provider class that
+ * holds the static handler method, paired with the name of that method —
+ * mirrors PHP's `[CliRouteProvider::class, 'testCommandHandler']`.
+ *
+ * Fix 1 (runtime) — the thunk is load-bearing, not decoration. A TC39 Stage-3
+ * method decorator runs while the enclosing class binding is still in its
+ * temporal dead zone, so naming a class directly (`[CliRouteProvider, 'x']`)
+ * dereferences it at class-definition time and throws `ReferenceError: Cannot
+ * access 'X' before initialization` whenever the referenced module is still
+ * initializing (a circular command ↔ provider import, or a command naming
+ * itself — which is exactly why `helpText` had to be dropped before). Building a
+ * closure never touches the binding, so the TDZ cannot fire; the collector calls
+ * `ref[0]()` later, once every module is initialized. Do not "simplify" this
+ * back to a bare class reference — the bare form is an order-dependent footgun
+ * and is deliberately not accepted.
+ */
+export type CliHandlerReference<T> = [() => T, CliHandlerKeys<T> & string];
+
+/**
+ * A help-text reference: a thunk returning the class holding a static method
+ * that returns the help message — mirrors PHP's `helpText: [self::class,
+ * 'help']`, written here as `helpText: [() => TestCommand, 'help']`. The thunk
+ * is what makes the self-reference legal (Fix 1).
+ */
+export type CliHelpTextReference<T> = [() => T, CliHelpTextKeys<T> & string];
+
+/**
+ * The loose storage forms of the references above. Only the authoring types are
+ * strict; once the metadata is written the concrete class type is no longer
+ * needed, so the stored tuple erases it.
+ */
+export type CliHandlerReferenceMetadata = [() => unknown, string];
+
+export type CliHelpTextReferenceMetadata = [() => unknown, string];
+
+/**
+ * A middleware class reference. The buckets it belongs to are resolved
+ * structurally by the collector, mirroring PHP's independent `is_a` checks.
+ */
+export type CliMiddlewareClass = new (
+    ...args: unknown[]
+) =>
+    | RouteMatchedMiddlewareContract
+    | RouteDispatchedMiddlewareContract
+    | ThrowableCaughtMiddlewareContract
+    | ProcessExitingMiddlewareContract;
+
+/**
+ * A middleware reference: a **thunk** returning the middleware class.
+ *
+ * Fix 1 (runtime) — the thunk is load-bearing, for the same reason as
+ * `CliHandlerReference`. Naming the class directly dereferences it while the
+ * decorator runs, which throws `ReferenceError: Cannot access 'X' before
+ * initialization` if that module is still initializing. Building a closure never
+ * touches the binding; the collector calls it once every module is ready.
+ */
+export type CliMiddlewareReference = () => CliMiddlewareClass;
+
+/**
+ * The accumulated metadata for a single `@Route` attribute on a command method.
+ * Repeatable decorators produce one definition each.
+ */
+export interface CliRouteDefinition {
+    name: string;
+    description: string;
+    handler: CliHandlerReferenceMetadata | null;
+    helpText: CliHelpTextReferenceMetadata | null;
+    middleware: CliMiddlewareReference[];
+}
+
+/**
+ * The accumulated metadata for a single command method: its route definitions
+ * plus the modifiers contributed by the other method-level decorators.
+ */
+export interface CliRouteMethodMetadata {
+    routes: CliRouteDefinition[];
+    handler: CliHandlerReferenceMetadata | null;
+    names: string[];
+    middleware: CliMiddlewareReference[];
+    arguments: ArgumentParameterOptions[];
+    options: OptionParameterOptions[];
+}
+
+/**
+ * The full attribute metadata attached to a command controller class.
+ */
+export interface CliRouteAttributeMetadata {
+    classNames: string[];
+    methods: Map<string, CliRouteMethodMetadata>;
+}
+
+/**
+ * The property key under which the CLI routing metadata is stored on the
+ * standard Stage-3 decorator metadata object.
+ */
+export const CLI_ROUTE_METADATA_KEY: unique symbol = Symbol('Valkyrja.Cli.Routing.Attribute.Metadata');
+
+/**
+ * Ensure `Symbol.metadata` exists so the collector can read decorator metadata
+ * off a class in runtimes that predate native support (Node, Vitest).
+ */
+export function ensureSymbolMetadata(): symbol {
+    const symbolWithMetadata = Symbol as { metadata: symbol | undefined };
+
+    symbolWithMetadata.metadata ??= Symbol.for('Symbol.metadata');
+
+    return symbolWithMetadata.metadata;
+}
+
+/**
+ * Get (creating if absent) the CLI routing metadata container on a decorator
+ * metadata object.
+ */
+export function ensureCliRouteMetadata(metadata: DecoratorMetadataObject): CliRouteAttributeMetadata {
+    const store = metadata as Record<symbol, CliRouteAttributeMetadata | undefined>;
+
+    return (store[CLI_ROUTE_METADATA_KEY] ??= {
+        classNames: [],
+        methods: new Map<string, CliRouteMethodMetadata>(),
+    });
+}
+
+/**
+ * Get (creating if absent) the metadata for a single command method.
+ */
+export function ensureCliRouteMethodMetadata(
+    metadata: DecoratorMetadataObject,
+    method: string | symbol,
+): CliRouteMethodMetadata {
+    const store = ensureCliRouteMetadata(metadata);
+    const name = method.toString();
+
+    let entry = store.methods.get(name);
+
+    if (entry === undefined) {
+        entry = {
+            routes: [],
+            handler: null,
+            names: [],
+            middleware: [],
+            arguments: [],
+            options: [],
+        };
+
+        store.methods.set(name, entry);
+    }
+
+    return entry;
+}
+
+/**
+ * Build a route definition from decorator options.
+ */
+export function createCliRouteDefinition<THandler, THelpText>(
+    options: CliRouteOptions<THandler, THelpText>,
+): CliRouteDefinition {
+    return {
+        name: options.name,
+        description: options.description,
+        handler: options.handler ?? null,
+        helpText: options.helpText ?? null,
+        middleware: options.middleware ?? [],
+    };
+}
+
+/**
+ * Read the CLI routing metadata a decorator wrote onto a command class, or
+ * `null` when the class carries no routing attributes.
+ */
+export function readCliRouteMetadata(target: new (...args: unknown[]) => unknown): CliRouteAttributeMetadata | null {
+    const metadataSymbol = ensureSymbolMetadata();
+    const metadata = (target as unknown as Record<symbol, DecoratorMetadataObject | undefined>)[metadataSymbol];
+
+    if (metadata === undefined) {
+        return null;
+    }
+
+    const store = metadata as Record<symbol, CliRouteAttributeMetadata | undefined>;
+
+    return store[CLI_ROUTE_METADATA_KEY] ?? null;
+}

package/src/Valkyrja/Cli/Routing/Attribute/RouteOptions.ts

@@ -0,0 +1,66 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Cast } from '../../../Type/Data/Cast.ts';
+import type { ArgumentMode } from '../Enum/ArgumentMode.ts';
+import type { ArgumentValueMode } from '../Enum/ArgumentValueMode.ts';
+import type { OptionMode } from '../Enum/OptionMode.ts';
+import type { OptionValueMode } from '../Enum/OptionValueMode.ts';
+import type { CliHandlerReference, CliHelpTextReference, CliMiddlewareReference } from './RouteAttributeMetadata.ts';
+
+/**
+ * The options accepted by the CLI `@Route` decorator, mirroring the named
+ * constructor arguments of PHP's `Valkyrja\Cli\Routing\Attribute\Route`.
+ */
+export interface CliRouteOptions<THandler = unknown, THelpText = unknown> {
+    name: string;
+    description: string;
+    /**
+     * The handler thunk/method-name pair. See `CliHandlerReference`: the thunk
+     * (Fix 1) sidesteps the decorator-time temporal dead zone, and the generic
+     * `THandler` (Fix 2) constrains the method name to a real handler on the
+     * referenced class.
+     */
+    handler?: CliHandlerReference<THandler>;
+    /**
+     * The help-text thunk/method-name pair, e.g. `[() => TestCommand, 'help']`.
+     * The thunk is what lets a command reference *itself* here (PHP's
+     * `self::class`) without tripping the temporal dead zone.
+     */
+    helpText?: CliHelpTextReference<THelpText>;
+    middleware?: CliMiddlewareReference[];
+}
+
+/**
+ * The options accepted by the `@ArgumentParameter` decorator, mirroring PHP's
+ * `Valkyrja\Cli\Routing\Attribute\ArgumentParameter`.
+ */
+export interface ArgumentParameterOptions {
+    name: string;
+    description: string;
+    cast?: Cast | null;
+    mode?: ArgumentMode;
+    valueMode?: ArgumentValueMode;
+}
+
+/**
+ * The options accepted by the `@OptionParameter` decorator, mirroring PHP's
+ * `Valkyrja\Cli\Routing\Attribute\OptionParameter`.
+ */
+export interface OptionParameterOptions {
+    name: string;
+    description: string;
+    valueDisplayName?: string;
+    cast?: Cast | null;
+    defaultValue?: string;
+    shortNames?: string[];
+    validValues?: string[];
+    mode?: OptionMode;
+    valueMode?: OptionValueMode;
+}

package/src/Valkyrja/Cli/Routing/Collector/AttributeRouteCollector.ts

@@ -0,0 +1,196 @@
+/*
+ * This file is part of the Valkyrja package.
+ *
+ * (c) Melech Mizrachi <melechmizrachi@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Output } from '../../Interaction/Output/Output.ts';
+import { readCliRouteMetadata } from '../Attribute/RouteAttributeMetadata.ts';
+import { ArgumentParameter } from '../Data/ArgumentParameter.ts';
+import { OptionParameter } from '../Data/OptionParameter.ts';
+import { Route } from '../Data/Route.ts';
+import { ArgumentMode } from '../Enum/ArgumentMode.ts';
+import { ArgumentValueMode } from '../Enum/ArgumentValueMode.ts';
+import { OptionMode } from '../Enum/OptionMode.ts';
+import { OptionValueMode } from '../Enum/OptionValueMode.ts';
+
+import type { OutputContract } from '../../Interaction/Output/Contract/OutputContract.ts';
+import type {
+    CliHandler,
+    CliHandlerReferenceMetadata,
+    CliHelpText,
+    CliHelpTextReferenceMetadata,
+    CliMiddlewareReference,
+    CliRouteDefinition,
+    CliRouteMethodMetadata,
+} from '../Attribute/RouteAttributeMetadata.ts';
+import type { ArgumentParameterOptions, OptionParameterOptions } from '../Attribute/RouteOptions.ts';
+import type { ArgumentParameterContract } from '../Data/Contract/ArgumentParameterContract.ts';
+import type { OptionParameterContract } from '../Data/Contract/OptionParameterContract.ts';
+import type { RouteContract } from '../Data/Contract/RouteContract.ts';
+import type { RouteCollectorContract } from './Contract/RouteCollectorContract.ts';
+
+/**
+ * Builds CLI commands from the decorator metadata attached to controller
+ * classes, without executing or re-parsing any source.
+ *
+ * Mirrors the framework's PHP `Cli\Routing\AttributeRouteCollector`, reading the
+ * standard Stage-3 decorator metadata (`Controller[Symbol.metadata]`) the CLI
+ * routing decorators write. Used on the uncached (debug) path.
+ */
+export class AttributeRouteCollector implements RouteCollectorContract {
+    getRoutes(...classes: Array<new (...args: unknown[]) => unknown>): RouteContract[] {
+        const routes: RouteContract[] = [];
+
+        for (const controller of classes) {
+            const metadata = readCliRouteMetadata(controller);
+
+            if (metadata === null) {
+                continue;
+            }
+
+            const className = metadata.classNames[0] ?? '';
+
+            for (const method of metadata.methods.values()) {
+                for (const definition of method.routes) {
+                    routes.push(this.buildRoute(definition, method, className));
+                }
+            }
+        }
+
+        return routes;
+    }
+
+    protected buildRoute(
+        definition: CliRouteDefinition,
+        method: CliRouteMethodMetadata,
+        className: string,
+    ): RouteContract {
+        const handler = this.resolveHandler(method.handler ?? definition.handler);
+        const helpText = this.resolveHelpText(definition.helpText);
+
+        let route: RouteContract = new Route(
+            definition.name,
+            definition.description,
+            handler,
+            helpText,
+            [],
+            [],
+            [],
+            [],
+            method.arguments.map((argument) => this.buildArgument(argument)),
+            method.options.map((option) => this.buildOption(option)),
+        );
+
+        route = this.applyName(route, className, method.names);
+        route = this.applyMiddleware(route, [...definition.middleware, ...method.middleware]);
+
+        return route;
+    }
+
+    /**
+     * Resolve the stored `[thunk, methodName]` pair into the handler closure.
+     *
+     * The first element is a thunk (Fix 1: it defers dereferencing the class
+     * past the decorator's temporal dead zone), so it must be *called* to get
+     * the class before the method can be indexed off it.
+     */
+    protected resolveHandler(reference: CliHandlerReferenceMetadata | null): CliHandler {
+        if (reference === null) {
+            return AttributeRouteCollector.defaultHandler;
+        }
+
+        const [provider, methodName] = reference;
+        const handler = (provider() as Record<string, CliHandler | undefined>)[methodName];
+
+        return handler ?? AttributeRouteCollector.defaultHandler;
+    }
+
+    /**
+     * Resolve the stored help-text `[thunk, methodName]` pair, calling the thunk
+     * for the same reason as `resolveHandler` — and it is precisely that
+     * deferral which lets a command point `helpText` at itself.
+     */
+    protected resolveHelpText(reference: CliHelpTextReferenceMetadata | null): CliHelpText | null {
+        if (reference === null) {
+            return null;
+        }
+
+        const [source, methodName] = reference;
+
+        return (source() as Record<string, CliHelpText | undefined>)[methodName] ?? null;
+    }
+
+    protected applyName(route: RouteContract, className: string, methodNames: string[]): RouteContract {
+        if (className !== '') {
+            route = route.withName(className + '.' + route.getName());
+        }
+
+        const methodName = methodNames[0];
+
+        if (methodName !== undefined) {
+            route = route.withName(route.getName() + '.' + methodName);
+        }
+
+        return route;
+    }
+
+    protected applyMiddleware(route: RouteContract, middleware: CliMiddlewareReference[]): RouteContract {
+        for (const thunk of middleware) {
+            // The reference is a thunk (see `CliMiddlewareReference`), so call it
+            // to get the class before inspecting its prototype.
+            const reference = thunk();
+            const prototype = reference.prototype as unknown as Record<string, unknown>;
+
+            if (typeof prototype.routeMatched === 'function') {
+                route = route.withAddedRouteMatchedMiddleware(reference.name);
+            }
+
+            if (typeof prototype.routeDispatched === 'function') {
+                route = route.withAddedRouteDispatchedMiddleware(reference.name);
+            }
+
+            if (typeof prototype.throwableCaught === 'function') {
+                route = route.withAddedThrowableCaughtMiddleware(reference.name);
+            }
+
+            if (typeof prototype.processExiting === 'function') {
+                route = route.withAddedProcessExitingMiddleware(reference.name);
+            }
+        }
+
+        return route;
+    }
+
+    protected buildArgument(options: ArgumentParameterOptions): ArgumentParameterContract {
+        return new ArgumentParameter(
+            options.name,
+            options.description,
+            options.cast ?? null,
+            options.mode ?? ArgumentMode.OPTIONAL,
+            options.valueMode ?? ArgumentValueMode.DEFAULT,
+        );
+    }
+
+    protected buildOption(options: OptionParameterOptions): OptionParameterContract {
+        return new OptionParameter(
+            options.name,
+            options.description,
+            options.valueDisplayName ?? '',
+            options.cast ?? null,
+            options.defaultValue ?? '',
+            options.shortNames ?? [],
+            options.validValues ?? [],
+            [],
+            options.mode ?? OptionMode.OPTIONAL,
+            options.valueMode ?? OptionValueMode.DEFAULT,
+        );
+    }
+
+    protected static defaultHandler(this: void): OutputContract {
+        return new Output();
+    }
+}

package/src/Valkyrja/Cli/Routing/Constant/CliRoutingServiceId.ts

@@ -10,6 +10,7 @@
 export class CliRoutingServiceId {
     static readonly RouterContract = 'Valkyrja.Cli.Routing.Dispatcher.RouterContract' as const;
     static readonly RouteCollectionContract = 'Valkyrja.Cli.Routing.Collection.RouteCollectionContract' as const;
+    static readonly RouteCollectorContract = 'Valkyrja.Cli.Routing.Collector.RouteCollectorContract' as const;
     static readonly RouteContract = 'Valkyrja.Cli.Routing.Data.RouteContract' as const;
     static readonly CliRoutingData = 'Valkyrja.Cli.Routing.Data.CliRoutingData' as const;
     static readonly CliRoutingConfig = 'Valkyrja.Cli.Routing.Data.CliRoutingConfig' as const;