@nestia/sdk 14.0.1 → 14.0.2

package/src/generates/internal/ImportDictionary.ts

@@ -11,6 +11,16 @@ import { ImportAnalyzer } from "../../analyses/ImportAnalyzer";
 import { IReflectImport } from "../../structures/IReflectImport";
 import { FilePrinter } from "./FilePrinter";
 
+/**
+ * The imports of one generated file, merged by module and kind, and printed as
+ * import declarations.
+ *
+ * @evidence contracts/common.md#principled-implementation An import is keyed by its module, its type-only flag, and its default or namespace name, so the same import is one declaration whose named bindings are collected in order.
+ * @evidence contracts/common.md#clear-and-simple-design One class with a hash map of components, and private helpers for the paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The keys are equal exactly when the declarations can be merged.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+ */
 export class ImportDictionary {
   private readonly components_: HashMap<ICompositeKey, ICompositeValue> =
     new HashMap(
@@ -24,10 +34,32 @@ export class ImportDictionary {
 
   public constructor(public readonly file: string) {}
 
+  /**
+   * Reports whether the file has no import.
+   *
+   * @evidence contracts/common.md#principled-implementation The dictionary is empty exactly when no component was registered.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the map.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.empty composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   public empty(): boolean {
     return this.components_.empty();
   }
 
+  /**
+   * Registers the imports a route's declarations need, merged by file, as
+   * type-only imports.
+   *
+   * The `WebSocketAcceptor` element is skipped, because the SDK refers to it
+   * through `tgrid`.
+   *
+   * @evidence contracts/common.md#principled-implementation Each namespace, default, and named import is registered under its alias so a name resolves to the same local binding.
+   * @evidence contracts/common.md#clear-and-simple-design One loop over the merged imports.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The skipped element is the one binding that the generated code supplies itself.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public declarations(imports: IReflectImport[]): void {
     imports = ImportAnalyzer.merge(imports);
     for (const imp of imports) {
@@ -59,7 +91,15 @@ export class ImportDictionary {
     }
   }
 
-  /** Every identifier the imports bind in the file. */
+  /**
+   * Every identifier the imports bind in the file.
+   *
+   * @evidence contracts/common.md#principled-implementation The namespace, the default, and each named local are collected, so a caller can see what a route name would shadow.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the components without changing them.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.locals composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   public locals(): string[] {
     const output: string[] = [];
     for (const { second: c } of this.components_) {
@@ -70,6 +110,44 @@ export class ImportDictionary {
     return output;
   }
 
+  /**
+   * Returns registered bindings in the route import representation, retaining
+   * normalized module paths and local-to-exported aliases. The route emitter
+   * consumes these as type-only declarations.
+   *
+   * @evidence contracts/common.md#principled-implementation The projection reads the same normalized module keys and local-to-exported binding map used by toStatements, so a structural type writer and its route retain the same imports.
+   * @evidence contracts/common.md#clear-and-simple-design One projection over existing registrations.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No AST parsing or second import policy reconstructs the bindings.
+   * @evidence contracts/common.md#meaningful-documentation Documents normalized paths, alias direction and the route's type-only consumption.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.toImports composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  public toImports(): IReflectImport[] {
+    return Array.from(this.components_).map(({ second: component }) => {
+      const bindings = Array.from(component.elements);
+      const aliases = Object.fromEntries(
+        bindings
+          .filter(({ first, second }) => first !== second)
+          .map(({ first, second }) => [first, second]),
+      );
+      return {
+        file: component.file,
+        asterisk: component.asterisk,
+        default: component.default,
+        elements: bindings.map(({ first }) => first),
+        ...(Object.keys(aliases).length ? { elementAliases: aliases } : {}),
+      };
+    });
+  }
+
+  /**
+   * Registers an import of a package and returns the local name it binds.
+   *
+   * @evidence contracts/common.md#principled-implementation The file is placed under `node_modules`, so the printer emits the bare package specifier.
+   * @evidence contracts/common.md#clear-and-simple-design One delegation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It shares the registration of `internal`.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public external(props: ImportDictionary.IProps): string {
     const file: string = `node_modules/${props.file}`;
     return this.internal({
@@ -78,6 +156,15 @@ export class ImportDictionary {
     });
   }
 
+  /**
+   * Registers an import of a source file and returns the local name it binds.
+   *
+   * @evidence contracts/common.md#principled-implementation The path is normalized and its source extension removed, so equal normalized module spellings share a component, and a named binding is stored under its local name. Symlink and filesystem-case identity are not canonicalized.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The result is the alias when there is one.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public internal(props: ImportDictionary.IProps): string {
     const file: string = normalize(trimSourceExtension(props.file));
     const key: ICompositeKey = {
@@ -97,6 +184,16 @@ export class ImportDictionary {
     return props.type === "element" ? (props.alias ?? props.name) : props.name;
   }
 
+  /**
+   * Returns the import declarations, packages first and files after them,
+   * sorted by module, with paths relative to the output directory.
+   *
+   * @evidence contracts/common.md#principled-implementation The package paths are cut at their last `node_modules`, and a file path is made relative with forward slashes, so the output does not depend on the platform.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one filter helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Both groups are sorted and separated by one empty line.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public toStatements(outDir: string): Node[] {
     outDir = path.resolve(outDir);
 
@@ -131,7 +228,7 @@ export class ImportDictionary {
           container.push(
             factory.createImportDeclaration(
               undefined,
-              this.toImportClaude(c),
+              this.toImportClause(c),
               factory.createStringLiteral(c.file),
             ),
           );
@@ -146,7 +243,7 @@ export class ImportDictionary {
     ];
   }
 
-  private toImportClaude(c: ICompositeValue): ImportClause {
+  private toImportClause(c: ICompositeValue): ImportClause {
     // A namespace binding cannot carry a per-binding `type` modifier, so the
     // type-only flag goes on the clause itself (`import type * as X`) —
     // generated SDK code references DTO namespaces only in type positions.
@@ -178,6 +275,16 @@ export class ImportDictionary {
   }
 }
 export namespace ImportDictionary {
+  /**
+   * One import to register: its kind, its module, its name, an optional alias,
+   * and whether it is type-only.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is the argument of both registrations.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   export interface IProps {
     type: "default" | "element" | "asterisk";
     file: string;

package/src/generates/internal/SdkAliasCollection.ts

@@ -18,7 +18,26 @@ import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 import type { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
+/**
+ * Type nodes of the SDK: the named types of routes, and the request and
+ * response aliases.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds each type as the syntax tree that the printer writes, from the reflected names or from the metadata when `clone` is on.
+ * @evidence contracts/common.md#clear-and-simple-design Several small builders.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The builders depend on the project configuration for the choice of source.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkAliasCollection {
+  /**
+   * Returns the type reference of a reflected type, with its type arguments.
+   *
+   * @evidence contracts/common.md#principled-implementation The arguments are built recursively.
+   * @evidence contracts/common.md#clear-and-simple-design One recursion.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It writes the name as reflected.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.name composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const name = ({ type }: { type: IReflectType }): TypeNode =>
     factory.createTypeReferenceNode(
       type.name,
@@ -27,20 +46,58 @@ export namespace SdkAliasCollection {
         : undefined,
     );
 
+  /**
+   * Returns the type of one chunk of a binary response:
+   * `Uint8Array<ArrayBufferLike>`.
+   *
+   * @evidence contracts/common.md#principled-implementation The chunk type of the platform stream is a byte array.
+   * @evidence contracts/common.md#clear-and-simple-design One node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The type is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.binaryChunk composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const binaryChunk = (): TypeNode =>
     factory.createTypeReferenceNode("Uint8Array", [
       factory.createTypeReferenceNode("ArrayBufferLike"),
     ]);
 
+  /**
+   * Returns the type of a binary response: `ReadableStream` of its chunks.
+   *
+   * @evidence contracts/common.md#principled-implementation A binary response is streamed, not read into memory.
+   * @evidence contracts/common.md#clear-and-simple-design One node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The chunk type is shared.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.binaryResponse composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const binaryResponse = (): TypeNode =>
     factory.createTypeReferenceNode("ReadableStream", [binaryChunk()]);
 
+  /**
+   * Returns the type node of a metadata.
+   *
+   * @evidence contracts/common.md#principled-implementation The metadata is written by the type programmer, so the result is the DTO the clone declares.
+   * @evidence contracts/common.md#clear-and-simple-design One delegation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It shares the type writer.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.from composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const from =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (metadata: MetadataSchema): TypeNode =>
       SdkTypeProgrammer.write(project)(importer)(metadata) as TypeNode;
 
+  /**
+   * Returns the object type of a route's keyword parameters, each with the
+   * description of its parameter or its `@param` tag.
+   *
+   * @evidence contracts/common.md#principled-implementation The entries are the route's path, query, and body parameters, optional where the metadata is, without prefix.
+   * @evidence contracts/common.md#clear-and-simple-design One map over the entries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A parameter with a description carries it as a comment.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.httpProps composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const httpProps =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -83,6 +140,16 @@ export namespace SdkAliasCollection {
           .flat(),
       );
 
+  /**
+   * Returns the object type of a WebSocket route's keyword parameters: its path
+   * parameters, its query, and its provider.
+   *
+   * @evidence contracts/common.md#principled-implementation The keys are the names decided by the parameter programmer, so the type and the function agree.
+   * @evidence contracts/common.md#clear-and-simple-design One literal.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names are shared.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.websocketProps composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const websocketProps = (
     route: ITypedWebSocketRoute,
     names: SdkWebSocketParameterProgrammer.INames,
@@ -114,6 +181,16 @@ export namespace SdkAliasCollection {
       ),
     ]);
 
+  /**
+   * Returns the type of a route's headers: its reflected name, or the
+   * metadata's type under `clone`.
+   *
+   * @evidence contracts/common.md#principled-implementation The source follows the `clone` setting.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The choice is made on one flag.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.headers composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const headers =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -133,6 +210,16 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's query: its metadata under `clone`, otherwise
+   * its reflected type wrapped in Resolved unless primitive conversion is off.
+   *
+   * @evidence contracts/common.md#principled-implementation Clone mode uses the resolved metadata graph; source mode uses the declared type with the configured Resolved conversion.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The choice is made on one flag.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.query composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const query =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -152,6 +239,16 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's body: a form data input for a multipart body,
+   * and otherwise the reflected name or the metadata's type under `clone`.
+   *
+   * @evidence contracts/common.md#principled-implementation The multipart body is an input of files and fields, not the declared class.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The cases are the content types.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.body composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const body =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -180,14 +277,28 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's output: the success and every exception as a
+   * union of `IPropagation` members, or the success body alone when propagation
+   * is off.
+   *
+   * @evidence contracts/common.md#principled-implementation Status keys retain their declared numeric or range spelling for IPropagation to expand. Source success types follow their content type, while declared exceptions use JSON Primitive conversion independently of the success media type; primitive:false preserves declared source types.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two branches.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The exceptions are the declared ones.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.response composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const response =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): TypeNode => {
-      const schema = (p: {
-        metadata: MetadataSchema;
-        type: IReflectType;
-      }): TypeNode =>
+      const schema = (
+        p: {
+          metadata: MetadataSchema;
+          type: IReflectType;
+        },
+        json: boolean,
+      ): TypeNode =>
         sizeOf(p.metadata) === 0
           ? TypeFactory.keyword("void")
           : project.config.clone === true
@@ -198,11 +309,7 @@ export namespace SdkAliasCollection {
                     file: "typia",
                     declaration: true,
                     type: "element",
-                    name:
-                      route.success.contentType === "application/json" ||
-                      route.success.encrypted === true
-                        ? "Primitive"
-                        : "Resolved",
+                    name: json ? "Primitive" : "Resolved",
                   }),
                   [name(p)],
                 )
@@ -210,7 +317,11 @@ export namespace SdkAliasCollection {
       const success: TypeNode =
         route.success.binary === true
           ? binaryResponse()
-          : schema(route.success);
+          : schema(
+              route.success,
+              route.success.contentType === "application/json" ||
+                route.success.encrypted === true,
+            );
       if (project.config.propagate !== true) return success;
 
       const branches: IBranch[] = [
@@ -222,7 +333,7 @@ export namespace SdkAliasCollection {
         },
         ...Object.entries(route.exceptions).map(([status, value]) => ({
           status,
-          type: schema(value),
+          type: schema(value, true),
         })),
       ];
       return factory.createTypeReferenceNode(
@@ -257,6 +368,17 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of the success body: a stream for a binary response, the
+   * reflected type for a plain one, and its primitive form for a JSON
+   * response.
+   *
+   * @evidence contracts/common.md#principled-implementation The route's metadata decides between the branches.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The branches are the response kinds.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.responseBody composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const responseBody =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>

package/src/generates/internal/SdkDistributionComposer.ts

@@ -4,97 +4,148 @@ import path from "path";
 
 import { INestiaConfig } from "../../INestiaConfig";
 
+/**
+ * Composes the npm package of the SDK in the distribution directory.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace copies the bundle, fills its paths in, and installs the dependencies at the versions the project uses.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the private steps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Each filesystem step resolves against the distribution directory; no process-global directory or foreign method is changed.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths use path.relative/path.join and generated paths use slash separators. npm receives an argument vector and an explicit cwd. POSIX launches npm directly; Windows launches the npm-cli.js shipped beside the first npm.cmd on PATH through Node because a cmd shim itself requires shell interpretation. A nonstandard Windows npm shim lacking that adjacent npm installation is rejected explicitly.
+ */
 export namespace SdkDistributionComposer {
+  /**
+   * Prepares the distribution package once: files, paths, and dependencies, and
+   * does nothing when the package is already configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The package counts as configured when it holds `@nestia/fetcher`, which is installed last with its peers, so an interrupted setup runs again. The caller directory is captured once, and every output path and package-manager cwd is explicit.
+   * @evidence contracts/common.md#clear-and-simple-design One function of sequential steps.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No process-global directory is changed, so independent compositions retain their own destinations.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Existence of the two package files is the filesystem's own answer, and the bundle files are copied over any file of the same name in a distribution directory that is not yet configured, so an interrupted setup repeats the copy.
+   */
   export const compose = async (props: {
     config: INestiaConfig;
     mcp: boolean;
     websocket: boolean;
   }) => {
-    if (!fs.existsSync(props.config.distribute!))
-      await fs.promises.mkdir(props.config.distribute!, { recursive: true });
-
     const root: string = process.cwd();
+    const directory: string = path.resolve(props.config.distribute!);
     const output: string = path.resolve(props.config.output!);
-    process.chdir(props.config.distribute!);
-    try {
-      if (await configured()) return;
-
-      // COPY FILES
-      console.log("Composing SDK distribution environments...");
-      for (const file of await fs.promises.readdir(BUNDLE))
-        await fs.promises.copyFile(`${BUNDLE}/${file}`, file);
-
-      // CONFIGURE PATHS
-      for (const file of ["package.json", "tsconfig.json"])
-        await replace({ root, output })(file);
+    await fs.promises.mkdir(directory, { recursive: true });
+    if (await configured(directory)) return;
 
-      // INSTALL PACKAGES
-      //
-      // The package compiles with ttsc, which applies the typia transform the
-      // SDK's `assert` and `simulate` code needs through typia's own plugin;
-      // typia removed its `setup` command in 14.0.0.
-      const v: IDependencies = await dependencies({
-        root,
-        websocket: props.websocket,
-      });
-      // one install per dependency kind: each npm run resolves and reifies the
-      // whole tree again, and the runtime set lands together or not at all, so
-      // an interrupted setup never leaves @nestia/fetcher, which marks the
-      // package configured, without its peers
-      execute(
-        `npm install --save-dev rimraf ttsc@${v.ttsc} typescript@${v.typescript}`,
-      );
-      execute(
-        [
-          "npm install --save",
-          `@nestia/fetcher@${v.version}`,
-          `typia@${v.typia}`,
-          ...(props.mcp && v.mcp !== undefined
-            ? [`@modelcontextprotocol/sdk@${v.mcp}`]
-            : []),
-          ...(props.websocket && v.tgrid !== undefined
-            ? [`tgrid@${v.tgrid}`]
-            : []),
-        ].join(" "),
+    console.log("Composing SDK distribution environments...");
+    for (const file of await fs.promises.readdir(BUNDLE))
+      await fs.promises.copyFile(
+        path.join(BUNDLE, file),
+        path.join(directory, file),
       );
-    } finally {
-      process.chdir(root);
-    }
+    for (const file of ["package.json", "tsconfig.json"])
+      await replace({ root, output, directory })(file);
+
+    // Compile with ttsc, which applies typia's transform; typia no longer has
+    // a setup command. Install each dependency kind together so an interrupted
+    // setup cannot mark @nestia/fetcher configured before its runtime peers.
+    const v: IDependencies = await dependencies({
+      root,
+      websocket: props.websocket,
+    });
+    execute(directory, [
+      "install",
+      "--save-dev",
+      "rimraf",
+      `ttsc@${v.ttsc}`,
+      `typescript@${v.typescript}`,
+    ]);
+    execute(directory, [
+      "install",
+      "--save",
+      `@nestia/fetcher@${v.version}`,
+      `typia@${v.typia}`,
+      ...(props.mcp && v.mcp !== undefined
+        ? [`@modelcontextprotocol/sdk@${v.mcp}`]
+        : []),
+      ...(props.websocket && v.tgrid !== undefined ? [`tgrid@${v.tgrid}`] : []),
+    ]);
   };
 
-  const configured = async (): Promise<boolean> =>
-    ["package.json", "tsconfig.json"].every(fs.existsSync) &&
+  const configured = async (directory: string): Promise<boolean> =>
+    ["package.json", "tsconfig.json"].every((file) =>
+      fs.existsSync(path.join(directory, file)),
+    ) &&
     (await (async () => {
       const content = JSON.parse(
-        await fs.promises.readFile("package.json", "utf8"),
+        await fs.promises.readFile(
+          path.join(directory, "package.json"),
+          "utf8",
+        ),
       );
       return !!content.dependencies?.["@nestia/fetcher"];
     })());
 
-  const execute = (command: string) => {
-    console.log(`  - ${command}`);
-    cp.execSync(command, { stdio: "ignore" });
+  const execute = (cwd: string, args: string[]): void => {
+    console.log(`  - npm ${args.join(" ")}`);
+    if (process.platform !== "win32")
+      cp.execFileSync("npm", args, { cwd, stdio: "ignore" });
+    else {
+      // Windows cannot execute npm.cmd without cmd.exe. Launch the JavaScript
+      // entry point installed beside that shim instead, so dependency ranges
+      // and paths never pass through a shell's metacharacter interpretation.
+      const directories = (process.env.PATH ?? "").split(path.delimiter);
+      const directory = directories.find((entry) =>
+        fs.existsSync(path.join(entry, "npm.cmd")),
+      );
+      const cli =
+        directory === undefined
+          ? undefined
+          : [
+              path.join(directory, "node_modules/npm/bin/npm-cli.js"),
+              path.resolve(directory, "../npm/bin/npm-cli.js"),
+            ].find((entry) => fs.existsSync(entry));
+      if (cli === undefined)
+        throw new Error(
+          "Unable to locate npm's JavaScript entry point beside npm.cmd on PATH.",
+        );
+      cp.execFileSync(process.execPath, [cli, ...args], {
+        cwd,
+        stdio: "ignore",
+      });
+    }
   };
 
   const replace =
-    (props: { root: string; output: string }) =>
+    (props: { root: string; output: string; directory: string }) =>
     async (file: string): Promise<void> => {
       const relative = (from: string) => (to: string) =>
         path.relative(from, to).split("\\").join("/");
-      const root: string = relative(process.cwd())(props.root);
-      const output: string = relative(process.cwd())(props.output);
-      const current: string = relative(props.root)(process.cwd());
-
-      const content: string = await fs.promises.readFile(file, "utf8");
+      const root: string = relative(props.directory)(props.root);
+      const output: string = relative(props.directory)(props.output);
+      const current: string = relative(props.root)(props.directory);
+      const replacements: Record<string, string> = { root, output, current };
+      const location: string = path.join(props.directory, file);
+      const content: unknown = JSON.parse(
+        await fs.promises.readFile(location, "utf8"),
+      );
+      const substitute = (value: unknown): unknown => {
+        if (typeof value === "string")
+          return value.replace(
+            /\$\{(root|output|current)\}/g,
+            (_match, key: string) => replacements[key]!,
+          );
+        if (Array.isArray(value)) return value.map(substitute);
+        if (value !== null && typeof value === "object")
+          return Object.fromEntries(
+            Object.entries(value).map(([key, element]) => [
+              key,
+              substitute(element),
+            ]),
+          );
+        return value;
+      };
       await fs.promises.writeFile(
-        file,
-        content
-          .split("${root}")
-          .join(root)
-          .split("${output}")
-          .join(output)
-          .split("${current}")
-          .join(current),
+        location,
+        JSON.stringify(substitute(content), null, 2) + "\n",
         "utf8",
       );
     };

package/src/generates/internal/SdkFileProgrammer.ts

@@ -15,10 +15,28 @@ import { SdkMcpRouteProgrammer } from "./SdkMcpRouteProgrammer";
 import { SdkRouteDirectory } from "./SdkRouteDirectory";
 import { SdkWebSocketRouteProgrammer } from "./SdkWebSocketRouteProgrammer";
 
+/**
+ * Writes the functional part of the SDK.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds the directory tree of the routes by accessor and prints one `index.ts` per directory.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The tree follows the accessors of the routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Node mkdir creates native directories from the configured output and analyzed identifier accessors; ImportDictionary separately renders relative module specifiers with forward slashes. No filesystem case equivalence is inferred from route names.
+ */
 export namespace SdkFileProgrammer {
   /* ---------------------------------------------------------
         CONSTRUCTOR
     --------------------------------------------------------- */
+  /**
+   * Writes the `functional` tree of the SDK from the routes' accessors.
+   *
+   * @evidence contracts/common.md#principled-implementation A route lands in the directory of its accessor without the last segment, and each directory exports its children as namespaces.
+   * @evidence contracts/common.md#clear-and-simple-design One tree build and one recursive writer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order of routes is the analysis order.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation The recursive writer passes output paths to Node fs and FilePrinter, which accept the slash suffixes on Windows and POSIX. Accessor analysis supplies valid namespace names; module specifier spelling remains the importer’s separate responsibility.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     // CONSTRUCT FOLDER TREE
     const root: SdkRouteDirectory = new SdkRouteDirectory(null, "functional");