@nestia/sdk 14.0.1 → 14.0.3

package/src/analyses/TypedMcpRouteAnalyzer.ts

@@ -1,31 +1,191 @@
+import {
+  MetadataAliasType,
+  MetadataArrayType,
+  MetadataComponents,
+  MetadataObjectType,
+  MetadataSchema,
+  MetadataTupleType,
+} from "../internal/legacy";
+import { IOperationMetadata } from "../structures/IOperationMetadata";
 import { IReflectController } from "../structures/IReflectController";
 import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { IReflectOperationError } from "../structures/IReflectOperationError";
 import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
 
+/**
+ * Turns a reflected MCP operation into a typed route.
+ *
+ * @evidence contracts/common.md#principled-implementation An MCP tool is one route whose accessor is `mcp` and the tool name with non-identifier characters replaced.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: The namespace groups declarations; analyze owns graph conversion.
+ * reuse equivalent work: The namespace coordinates no computation.
+ * bound retention and release resources: The namespace owns no retained state or handles.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedMcpRouteAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace TypedMcpRouteAnalyzer {
+  /**
+   * Returns the typed route of an MCP tool: its names, schemas, input
+   * parameter, return type, and imports. Clone mode resolves a private copy of
+   * the native JSON graph and reports missing or unresolved components.
+   *
+   * @evidence contracts/common.md#principled-implementation Native primitive pipes describe the same JSON wire values the MCP adaptor serializes. Clone requests require these graphs; source-only routes preserve their declared types and imports.
+   * @evidence contracts/common.md#clear-and-simple-design One conversion resolves the input and output against their own components and reports clone metadata failures at the route.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Native JSON pipes are resolved through the shared metadata adapter; source binding names never select a clone exception and native records remain unchanged.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * efficient algorithms: Clone mode copies each supplied graph payload once, indexes its components and visits each schema and component target once to check reference closure. Work scales with graph vertices, edges and annotation payload; no compiler or type analysis is repeated.
+   * reuse equivalent work: Input and output pipes have independent native component identities, and this operation retains no completed or in-flight request to share across analyses.
+   * bound retention and release resources: Resolution copies and visited sets belong to one synchronous conversion; the returned route retains its reachable graphs, and no global cache, process or handle is created.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedMcpRouteAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: {
     controller: IReflectController;
     operation: IReflectMcpOperation;
-  }): ITypedMcpRoute[] => [
-    {
-      protocol: "mcp",
-      controller: props.controller,
-      name: props.operation.name,
-      toolName: props.operation.toolName,
-      title: props.operation.title,
-      toolDescription: props.operation.toolDescription,
-      accessor: accessor(props.operation.toolName),
-      function: props.operation.function,
-      input: props.operation.parameters[0] ?? null,
-      returnType: props.operation.returnType,
-      inputSchema: props.operation.inputSchema,
-      outputSchema: props.operation.outputSchema,
-      annotations: props.operation.annotations,
-      imports: props.operation.imports,
-      description: props.operation.description,
-      jsDocTags: props.operation.jsDocTags,
-    },
-  ];
+    clone?: boolean;
+    errors?: IReflectOperationError[];
+  }): ITypedMcpRoute[] => {
+    const errors: Array<string | IOperationMetadata.IError> = [];
+    const cast = (
+      pipe: IOperationMetadata.IResponse["primitive"] | undefined,
+      position: string,
+    ): MetadataSchema | undefined => {
+      if (props.clone !== true) return undefined;
+      if (pipe === undefined) {
+        errors.push(`Missing native JSON metadata for MCP ${position}.`);
+        return undefined;
+      }
+      if (pipe.success === false) {
+        errors.push(...pipe.errors);
+        return undefined;
+      }
+      try {
+        const data = structuredClone(pipe.data);
+        const components = MetadataComponents.from(data.components);
+        const metadata = MetadataSchema.from(
+          data.metadata,
+          components.dictionary,
+        );
+        const visited = new WeakSet<object>();
+        const inspect = (value: MetadataSchema): void => {
+          if (visited.has(value)) return;
+          visited.add(value);
+          for (const kind of [
+            "objects",
+            "aliases",
+            "arrays",
+            "tuples",
+          ] as const) {
+            if (!Array.isArray(value[kind]))
+              throw new Error(`Missing ${kind} metadata.`);
+            for (const reference of value[kind]) {
+              const target = (
+                reference as typeof reference & {
+                  type?:
+                    | MetadataObjectType
+                    | MetadataAliasType
+                    | MetadataArrayType
+                    | MetadataTupleType;
+                }
+              ).type;
+              if (target === undefined)
+                throw new Error(
+                  `Unresolved ${kind} component ${reference.name}.`,
+                );
+              if (visited.has(target)) continue;
+              visited.add(target);
+              if (kind === "objects")
+                for (const property of (target as MetadataObjectType)
+                  .properties) {
+                  inspect(property.key);
+                  inspect(property.value);
+                }
+              else if (kind === "tuples")
+                for (const element of (target as MetadataTupleType).elements)
+                  inspect(element);
+              else
+                inspect(
+                  (target as MetadataAliasType | MetadataArrayType).value,
+                );
+            }
+          }
+          if (value.rest) inspect(value.rest);
+          if (value.escaped) {
+            inspect(value.escaped.original);
+            inspect(value.escaped.returns);
+          }
+          for (const template of value.templates)
+            for (const element of template.row ?? template) inspect(element);
+          for (const set of value.sets) inspect(set.value);
+          for (const map of value.maps) {
+            inspect(map.key);
+            inspect(map.value);
+          }
+          for (const fn of value.functions) {
+            for (const parameter of fn.parameters) inspect(parameter.type);
+            inspect(fn.output);
+          }
+        };
+        if (!Array.isArray(metadata.objects))
+          throw new Error("Missing schema metadata.");
+        inspect(metadata);
+        return metadata;
+      } catch (error) {
+        errors.push(
+          `Invalid native JSON metadata for MCP ${position}: ${String(error)}`,
+        );
+        return undefined;
+      }
+    };
+    const inputMetadata = props.operation.parameters[0]
+      ? cast(props.operation.parameters[0].metadata, "input")
+      : undefined;
+    const outputMetadata = cast(props.operation.returnMetadata, "output");
+    if (errors.length) {
+      const failure: IReflectOperationError = {
+        file: props.controller.file,
+        class: props.controller.class.name,
+        function: props.operation.name,
+        from: props.operation.name,
+        contents: errors,
+      };
+      if (props.errors === undefined)
+        throw new Error(
+          errors
+            .map((e) => (typeof e === "string" ? e : e.messages.join("; ")))
+            .join("\n"),
+        );
+      props.errors.push(failure);
+      return [];
+    }
+    return [
+      {
+        protocol: "mcp",
+        controller: props.controller,
+        name: props.operation.name,
+        toolName: props.operation.toolName,
+        title: props.operation.title,
+        toolDescription: props.operation.toolDescription,
+        accessor: accessor(props.operation.toolName),
+        function: props.operation.function,
+        input: props.operation.parameters[0]
+          ? {
+              ...props.operation.parameters[0],
+              type: { ...props.operation.parameters[0].type },
+            }
+          : null,
+        returnType: props.operation.returnType,
+        inputMetadata,
+        outputMetadata,
+        inputSchema: props.operation.inputSchema,
+        outputSchema: props.operation.outputSchema,
+        annotations: props.operation.annotations,
+        imports: props.operation.imports,
+        description: props.operation.description,
+        jsDocTags: props.operation.jsDocTags,
+      },
+    ];
+  };
 
   const accessor = (toolName: string): string[] => {
     const safe = toolName.replace(/[^A-Za-z0-9_$]/g, "_");

package/src/analyses/TypedWebSocketRouteAnalyzer.ts

@@ -3,7 +3,26 @@ import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOpera
 import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
 import { PathUtil } from "../utils/PathUtil";
 
+/**
+ * Turns a reflected WebSocket operation into typed routes, one per path.
+ *
+ * @evidence contracts/common.md#principled-implementation Each path gets an accessor from its segments and the method name, and the parameters are split by category.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace TypedWebSocketRouteAnalyzer {
+  /**
+   * Returns one typed WebSocket route per path, with the header, path
+   * parameters, query, acceptor, and driver separated.
+   *
+   * @evidence contracts/common.md#principled-implementation The parameters are filtered by category, the acceptor is required by the reflection, and the accessor combines the path segments and the method name.
+   * @evidence contracts/common.md#clear-and-simple-design One mapping.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It only reorganizes reflected data.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: {
     controller: IReflectController;
     operation: IReflectWebSocketOperation;

package/src/decorators/OperationMetadata.ts

@@ -9,6 +9,12 @@ import { IOperationMetadata } from "../structures/IOperationMetadata";
  * object literal — keeping the constructed node tree minimal. The string is
  * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
  * object is still accepted for hand-written or test usage.
+ *
+ * @evidence contracts/common.md#principled-implementation The metadata is defined on the class prototype and property key, from an object or its JSON text, which is the key the reflection analyzers look up.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator that parses when given text and defines one metadata entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only records what the transform computed and does not alter the method.
+ * @evidence contracts/common.md#meaningful-documentation The comment states who emits and who reads the metadata.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation OperationMetadata attaches metadata through Reflect.defineMetadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export function OperationMetadata(
   metadata: IOperationMetadata | string,

package/src/executable/internal/CommandParser.ts

@@ -1,4 +1,23 @@
+/**
+ * Parses the command-line flags of the `nestia` command.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace reads `--key value` pairs from an argument list.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain parser.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace CommandParser {
+  /**
+   * Returns the `--key value` pairs of an argument list as an object; a flag
+   * without a value, or followed by another flag, is left out.
+   *
+   * @evidence contracts/common.md#principled-implementation Each argument that starts with two dashes is a key, and the next argument is its value only when it exists and is not itself a flag.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It applies to every argument.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the omitted flags.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser.parse parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export function parse(argList: string[]): Record<string, string> {
     const output: Record<string, string> = {};
     argList.forEach((arg, i) => {

package/src/executable/internal/NestiaConfigLoader.ts

@@ -5,16 +5,57 @@ import { pathToFileURL } from "url";
 
 import { INestiaConfig } from "../../INestiaConfig";
 import { EmittedJavaScriptPatcher } from "../../utils/EmittedJavaScriptPatcher";
+import { TemporaryDirectory } from "../../utils/TemporaryDirectory";
 import { TsConfigReader } from "../../utils/TsConfigReader";
 import { TtscExecutor } from "../../utils/TtscExecutor";
 
+/**
+ * Loads the TypeScript configuration of a project and its `nestia.config.ts`.
+ *
+ * @evidence contracts/common.md#principled-implementation The project file is found and merged with its `extends` chain, and the configuration is compiled through ttsc with the nestia plugin into a temporary directory, imported, and validated by type checks of the input, the scalar options and the swagger options; the swagger `info`, `servers`, `security` and `tags` values are passed on unchecked.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions with private helpers for the temporary roots, the plugin list, and the validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only this process's unique materializations are removed on exit and handled termination signals; shared cache parents and other processes' children remain, and a compile error is reported with the compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: Project inheritance delegates one per-read traversal to TsConfigReader; configuration loading compiles one wrapper project, patches emitted JavaScript once and validates each returned config.
+ * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+ * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+ * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+ */
 export namespace NestiaConfigLoader {
+  /**
+   * The compiler options of a project as the loader reads them: the raw
+   * `compilerOptions` object.
+   *
+   * @evidence contracts/common.md#principled-implementation The record wraps the raw options so callers can read them without a compiler API.
+   * @evidence contracts/common.md#clear-and-simple-design A one-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * efficient algorithms: The compiler-options record represents parsed values and selects no algorithm.
+   * reuse equivalent work: This record coordinates no configuration loads or shared producers.
+   * bound retention and release resources: This record owns neither materialization cleanup nor compiler tasks.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation The raw compiler option record performs no native path resolution or process launch; its loader owns those boundaries.
+   */
   export interface ICompilerOptions {
     raw: {
       compilerOptions?: Record<string, any>;
     };
   }
 
+  /**
+   * Returns the merged compiler options of the project file, following its
+   * `extends` chain.
+   *
+   * It throws when the file cannot be found.
+   *
+   * @evidence contracts/common.md#principled-implementation The file is searched upward from the working directory when the name is relative, and `TsConfigReader` merges the chain, so the options are those the compiler would use.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the reading.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads what the compiler reads.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and the error.
+   * efficient algorithms: Upward project search visits each ancestor directory once, and TsConfigReader shares repeated ancestors inside one read.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+   * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+   */
   export const compilerOptions = async (
     project: string,
   ): Promise<ICompilerOptions> => {
@@ -31,6 +72,22 @@ export namespace NestiaConfigLoader {
     };
   };
 
+  /**
+   * Returns the configurations exported by a `nestia.config.ts`, validated.
+   *
+   * The file is compiled through ttsc with the nestia plugin into a temporary
+   * directory and imported; a missing file, a compile error, or an invalid
+   * field is an error.
+   *
+   * @evidence contracts/common.md#principled-implementation The wrapper project extends the user's project with emit forced on and declarations off, the typia plugin disabled and the nestia one enabled, the emitted file is patched for `import.meta.url`, and the exported value is checked for its input, scalar options and swagger options, so a malformed one is rejected before generation, while the OpenAPI `info`, `servers`, `security` and `tags` values are not inspected here.
+   * @evidence contracts/common.md#clear-and-simple-design One function over private helpers for compilation, extraction, and validation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shared registry removes only owned children on exit and handled termination signals, and the checks follow the `INestiaConfig` contract.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the compile step and the errors.
+   * efficient algorithms: Each invocation compiles one wrapper project, traverses its emitted JavaScript once and validates each returned config and option field.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+   * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+   */
   export const configurations = async (
     file: string,
     compilerOptions: Record<string, any>,
@@ -59,9 +116,6 @@ export namespace NestiaConfigLoader {
     return assertConfigurations(file, configurations);
   };
 
-  const MATERIALIZED_ROOTS: Set<string> = new Set();
-  let CLEANUP_REGISTERED: boolean = false;
-
   const materializeConfiguration = async (props: {
     file: string;
     compilerOptions: Record<string, any>;
@@ -76,11 +130,13 @@ export namespace NestiaConfigLoader {
       throw new Error(`unable to find "${project}" file.`);
 
     const projectRoot: string = path.dirname(path.resolve(projectFile));
-    const wrapperRoot: string = fs.mkdtempSync(
-      path.join(ensureMaterializedRoot(projectRoot), "tsconfig-"),
+    const wrapperRoot: string = TemporaryDirectory.create(
+      materializedRoot(projectRoot),
+      "tsconfig-",
     );
-    const outputRoot: string = fs.mkdtempSync(
-      path.join(ensureMaterializedRoot(projectRoot), "run-"),
+    const outputRoot: string = TemporaryDirectory.create(
+      materializedRoot(projectRoot),
+      "run-",
     );
     const wrapperFile: string = path.join(wrapperRoot, "tsconfig.json");
     const wrapperConfig = {
@@ -130,7 +186,7 @@ export namespace NestiaConfigLoader {
         { cause },
       );
     } finally {
-      fs.rmSync(wrapperRoot, { force: true, recursive: true });
+      TemporaryDirectory.remove(wrapperRoot);
     }
     await EmittedJavaScriptPatcher.importMetaUrl(outputRoot);
 
@@ -143,48 +199,8 @@ export namespace NestiaConfigLoader {
     return next;
   };
 
-  const ensureMaterializedRoot = (projectRoot: string): string => {
-    const root: string = path.join(
-      projectRoot,
-      "node_modules",
-      ".nestia",
-      "config-loader",
-    );
-    fs.mkdirSync(root, { recursive: true });
-    MATERIALIZED_ROOTS.add(root);
-    if (CLEANUP_REGISTERED === false) {
-      CLEANUP_REGISTERED = true;
-      const sweep = (): void => {
-        for (const location of MATERIALIZED_ROOTS)
-          fs.rmSync(location, { force: true, recursive: true });
-      };
-      process.once("exit", sweep);
-      // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without
-      // these handlers a Ctrl-C during codegen leaves `run-*` and
-      // `tsconfig-*` mkdtempSync directories behind under
-      // node_modules/.nestia/config-loader/ until a subsequent clean exit.
-      // The module-level CLEANUP_REGISTERED flag above guards against
-      // re-entrancy within this module; we deliberately do NOT gate on
-      // `process.listenerCount(signal) > 0` because the parallel sweep in
-      // `ConfigAnalyzer.ensureRuntimeCleanup` (or any user-app SIGINT
-      // handler) could register first, and that gate would skip our
-      // registration — leaving MATERIALIZED_ROOTS unswept on Ctrl-C.
-      // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
-      // rather than re-raising; whichever module registers FIRST runs its
-      // sweep, the second is skipped, RUNTIME/MATERIALIZED cleanup is
-      // best-effort on Windows. SIGHUP is a no-op for most common code
-      // paths on Windows (Node fires it on console-close and exits within
-      // seconds).
-      const onSignal = (signal: NodeJS.Signals): void => {
-        sweep();
-        process.kill(process.pid, signal);
-      };
-      for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-        process.once(signal, onSignal);
-      }
-    }
-    return root;
-  };
+  const materializedRoot = (projectRoot: string): string =>
+    path.join(projectRoot, "node_modules", ".nestia", "config-loader");
 
   const emittedJavaScriptKey = (projectRoot: string, file: string): string => {
     const relative: string = path.relative(projectRoot, file);

package/src/executable/internal/NestiaSdkCommand.ts

@@ -2,8 +2,31 @@ import { INestiaConfig } from "../../INestiaConfig";
 import { NestiaSdkApplication } from "../../NestiaSdkApplication";
 import { NestiaConfigLoader } from "./NestiaConfigLoader";
 import { NestiaSdkWatcher } from "./NestiaSdkWatcher";
+import { NestiaSwaggerWatch } from "./NestiaSwaggerWatch";
 
+/**
+ * The commands of the `nestia` CLI that run the generators: `sdk`, `swagger`,
+ * `e2e`, and `all`.
+ *
+ * @evidence contracts/common.md#principled-implementation Each command loads the configurations, keeps the ones that can generate what it needs, and runs the application; `swagger` can watch.
+ * @evidence contracts/common.md#clear-and-simple-design Four commands over one private runner and two argument readers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The commands differ only by title, validation, and generator.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Project and config arguments remain native pathname strings supplied to NestiaConfigLoader and NestiaSdkWatcher. Those owners resolve files and launch compiler processes; dispatch does not rewrite path case or separators.
+ */
 export namespace NestiaSdkCommand {
+  /**
+   * Runs the generator of the SDK library for every valid configuration.
+   *
+   * With several configurations, those that cannot generate this output are
+   * skipped, and it is an error when none can.
+   *
+   * @evidence contracts/common.md#principled-implementation The project and configuration files come from the `--project` and `--config` flags with defaults, each flag's value is checked, and the shared runner applies the configurations in order.
+   * @evidence contracts/common.md#clear-and-simple-design One binding of the shared runner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The behavior follows the flags and the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the skipping rule.
+   * @evidence contracts/portability.md#os-neutral-implementation Project and config arguments remain native pathname strings supplied to NestiaConfigLoader and NestiaSdkWatcher. Those owners resolve files and launch compiler processes; dispatch does not rewrite path case or separators.
+   */
   export const sdk = () =>
     main({
       title: "SDK library",
@@ -12,6 +35,19 @@ export namespace NestiaSdkCommand {
       solution: "configure INestiaConfig.output property.",
     });
 
+  /**
+   * Runs the generator of the Swagger document, optionally in watch mode for
+   * every valid configuration.
+   *
+   * With several configurations, those that cannot generate this output are
+   * skipped, and it is an error when none can.
+   *
+   * @evidence contracts/common.md#principled-implementation The project and configuration files come from the `--project` and `--config` flags with defaults, each flag's value is checked, and the shared runner applies the configurations in order.
+   * @evidence contracts/common.md#clear-and-simple-design One binding of the shared runner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The behavior follows the flags and the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the skipping rule.
+   * @evidence contracts/portability.md#os-neutral-implementation Project and config arguments remain native pathname strings supplied to NestiaConfigLoader and NestiaSdkWatcher. Those owners resolve files and launch compiler processes; dispatch does not rewrite path case or separators.
+   */
   export const swagger = () =>
     main({
       title: "Swagger Document",
@@ -21,6 +57,18 @@ export namespace NestiaSdkCommand {
       watch: hasFlagArgument("watch"),
     });
 
+  /**
+   * Runs the generator of the e2e test functions for every valid configuration.
+   *
+   * With several configurations, those that cannot generate this output are
+   * skipped, and it is an error when none can.
+   *
+   * @evidence contracts/common.md#principled-implementation The project and configuration files come from the `--project` and `--config` flags with defaults, each flag's value is checked, and the shared runner applies the configurations in order.
+   * @evidence contracts/common.md#clear-and-simple-design One binding of the shared runner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The behavior follows the flags and the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the skipping rule.
+   * @evidence contracts/portability.md#os-neutral-implementation Project and config arguments remain native pathname strings supplied to NestiaConfigLoader and NestiaSdkWatcher. Those owners resolve files and launch compiler processes; dispatch does not rewrite path case or separators.
+   */
   export const e2e = () =>
     main({
       title: "E2E Functions",
@@ -34,6 +82,19 @@ export namespace NestiaSdkCommand {
       ].join("\n"),
     });
 
+  /**
+   * Runs the generator of everything the configurations ask for for every valid
+   * configuration.
+   *
+   * With several configurations, those that cannot generate this output are
+   * skipped, and it is an error when none can.
+   *
+   * @evidence contracts/common.md#principled-implementation The project and configuration files come from the `--project` and `--config` flags with defaults, each flag's value is checked, and the shared runner applies the configurations in order.
+   * @evidence contracts/common.md#clear-and-simple-design One binding of the shared runner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The behavior follows the flags and the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the skipping rule.
+   * @evidence contracts/portability.md#os-neutral-implementation Project and config arguments remain native pathname strings supplied to NestiaConfigLoader and NestiaSdkWatcher. Those owners resolve files and launch compiler processes; dispatch does not rewrite path case or separators.
+   */
   export const all = () =>
     main({
       title: "everything",
@@ -90,13 +151,45 @@ export namespace NestiaSdkCommand {
       }
     };
 
-    if (props.watch === true)
+    if (props.watch === true) {
+      let generation: NestiaSwaggerWatch.IGeneration | undefined;
+      let opening: Promise<NestiaSwaggerWatch.IGeneration> | undefined;
+      let cancellation: AbortController | undefined;
       return NestiaSdkWatcher.watch({
         configFile,
-        configurations,
-        generate,
+        configurations: async () => {
+          cancellation = new AbortController();
+          opening = NestiaSwaggerWatch.open({
+            configFile,
+            projectFile: project,
+            signal: cancellation.signal,
+          });
+          generation = await opening;
+          return generation.configurations;
+        },
+        generate: async () => {
+          if (!generation)
+            throw new Error("Swagger watch generation was not prepared.");
+          await generation.generate();
+        },
+        finalize: async () => {
+          cancellation?.abort();
+          try {
+            await opening?.then(
+              (prepared) => prepared.close(),
+              (error: Error) => {
+                if (error.name !== "AbortError") throw error;
+              },
+            );
+          } finally {
+            generation = undefined;
+            opening = undefined;
+            cancellation = undefined;
+          }
+        },
         projectFile: project,
       });
+    }
 
     await generate(await configurations());
   };