@dudousxd/nestjs-inertia-codegen 1.2.0 → 1.4.0

package/dist/cli/main.cjs

@@ -248,16 +248,6 @@ function validateNameSegment(seg, fullName) {
   }
 }
 __name(validateNameSegment, "validateNameSegment");
-function detectCollisions(tree, name) {
-  for (const [key, node] of tree) {
-    if (node.kind === "leaf") {
-    } else {
-      void key;
-    }
-  }
-  void name;
-}
-__name(detectCollisions, "detectCollisions");
 function insertIntoTree(tree, segments, leaf, fullName) {
   const head = segments[0];
   const rest = segments.slice(1);
@@ -287,7 +277,30 @@ function insertIntoTree(tree, segments, leaf, fullName) {
   }
 }
 __name(insertIntoTree, "insertIntoTree");
-function emitRouterTypeBlock(tree, indent) {
+function buildParamsType(params) {
+  const pathParams = params.filter((p) => p.source === "path");
+  if (pathParams.length === 0) return "never";
+  return `{ ${pathParams.map((p) => `${p.name}: string`).join("; ")} }`;
+}
+__name(buildParamsType, "buildParamsType");
+function hasPathParams(params) {
+  return params.some((p) => p.source === "path");
+}
+__name(hasPathParams, "hasPathParams");
+function buildResponseType(c, outDir) {
+  if (c.controllerRef) {
+    let relPath = (0, import_node_path3.relative)(outDir, c.controllerRef.filePath).replace(/\.ts$/, "");
+    if (!relPath.startsWith(".")) relPath = `./${relPath}`;
+    return `Awaited<ReturnType<import('${relPath}').${c.controllerRef.className}['${c.controllerRef.methodName}']>>`;
+  }
+  const respRef = c.contractSource.responseRef;
+  if (respRef) {
+    return respRef.isArray ? `Array<${respRef.name}>` : respRef.name;
+  }
+  return c.contractSource.response;
+}
+__name(buildResponseType, "buildResponseType");
+function emitRouterTypeBlock(tree, indent, outDir) {
   const pad = " ".repeat(indent);
   const lines = [];
   for (const [key, node] of tree) {
@@ -299,14 +312,14 @@ function emitRouterTypeBlock(tree, indent) {
       const query = queryRef ? queryRef.isArray ? `Array<${queryRef.name}>` : queryRef.name : c.contractSource.query ?? "never";
       const bodyRef = c.contractSource.bodyRef;
       const body = method === "GET" ? "never" : bodyRef ? bodyRef.isArray ? `Array<${bodyRef.name}>` : bodyRef.name : c.contractSource.body ?? "never";
-      const respRef = c.contractSource.responseRef;
-      const response = respRef ? respRef.isArray ? `Array<${respRef.name}>` : respRef.name : c.contractSource.response;
+      const response = buildResponseType(c, outDir);
+      const params = buildParamsType(c.params);
       const safeMethod = JSON.stringify(method);
       const safeUrl = JSON.stringify(c.path);
-      lines.push(`${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; query: ${query}; body: ${body}; response: ${response} };`);
+      lines.push(`${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response} };`);
     } else {
       lines.push(`${pad}${objKey}: {`);
-      lines.push(...emitRouterTypeBlock(node.children, indent + 2));
+      lines.push(...emitRouterTypeBlock(node.children, indent + 2, outDir));
       lines.push(`${pad}};`);
     }
   }
@@ -326,20 +339,61 @@ function emitApiObjectBlock(tree, indent) {
       const fetcherMethod = method.toLowerCase();
       if (method === "GET") {
         const typeAccess = buildRouterTypeAccess(c.name);
+        const withParams = hasPathParams(c.params);
         lines.push(`${pad}${objKey}: {`);
-        lines.push(`${pad}  queryKey: (query?: ${typeAccess}['query']) => query !== undefined ? [${flatName}, query] as const : [${flatName}] as const,`);
-        lines.push(`${pad}  queryOptions: (query?: ${typeAccess}['query']) => ({`);
-        lines.push(`${pad}    queryKey: query !== undefined ? [${flatName}, query] as const : [${flatName}] as const,`);
-        lines.push(`${pad}    queryFn: () => fetcher.get<${typeAccess}['response']>(route(${flatName} as never) || ${safePath}, { query }),`);
-        lines.push(`${pad}  }),`);
+        if (withParams) {
+          lines.push(`${pad}  queryKey: (params: ${typeAccess}['params'], query?: ${typeAccess}['query']) => query !== undefined ? [${flatName}, params, query] as const : [${flatName}, params] as const,`);
+          lines.push(`${pad}  queryOptions: (params: ${typeAccess}['params'], query?: ${typeAccess}['query']) =>`);
+          lines.push(`${pad}    _queryOptions({`);
+          lines.push(`${pad}      queryKey: query !== undefined ? [${flatName}, params, query] as const : [${flatName}, params] as const,`);
+          lines.push(`${pad}      queryFn: () => fetcher.get<${typeAccess}['response']>(route(${flatName} as never, params as never) || ${safePath}, { query }),`);
+          lines.push(`${pad}    }),`);
+          lines.push(`${pad}  infiniteQueryOptions: (params: ${typeAccess}['params'], query?: ${typeAccess}['query']) => ({`);
+          lines.push(`${pad}    queryKey: query !== undefined ? [${flatName}, params, query] as const : [${flatName}, params] as const,`);
+          lines.push(`${pad}    queryFn: ({ pageParam }: { pageParam: number }) => fetcher.get<${typeAccess}['response']>(route(${flatName} as never, params as never) || ${safePath}, { query: { ...query, page: pageParam } }),`);
+          lines.push(`${pad}    initialPageParam: 1,`);
+          lines.push(`${pad}    getNextPageParam: (lastPage: ${typeAccess}['response']) => {`);
+          lines.push(`${pad}      const meta = (lastPage as any)?.meta;`);
+          lines.push(`${pad}      if (meta?.page != null && meta?.lastPage != null) {`);
+          lines.push(`${pad}        return meta.page < meta.lastPage ? meta.page + 1 : undefined;`);
+          lines.push(`${pad}      }`);
+          lines.push(`${pad}      return undefined;`);
+          lines.push(`${pad}    },`);
+          lines.push(`${pad}  }),`);
+        } else {
+          lines.push(`${pad}  queryKey: (query?: ${typeAccess}['query']) => query !== undefined ? [${flatName}, query] as const : [${flatName}] as const,`);
+          lines.push(`${pad}  queryOptions: (query?: ${typeAccess}['query']) =>`);
+          lines.push(`${pad}    _queryOptions({`);
+          lines.push(`${pad}      queryKey: query !== undefined ? [${flatName}, query] as const : [${flatName}] as const,`);
+          lines.push(`${pad}      queryFn: () => fetcher.get<${typeAccess}['response']>(route(${flatName} as never) || ${safePath}, { query }),`);
+          lines.push(`${pad}    }),`);
+          lines.push(`${pad}  infiniteQueryOptions: (query?: ${typeAccess}['query']) => ({`);
+          lines.push(`${pad}    queryKey: query !== undefined ? [${flatName}, query] as const : [${flatName}] as const,`);
+          lines.push(`${pad}    queryFn: ({ pageParam }: { pageParam: number }) => fetcher.get<${typeAccess}['response']>(route(${flatName} as never) || ${safePath}, { query: { ...query, page: pageParam } }),`);
+          lines.push(`${pad}    initialPageParam: 1,`);
+          lines.push(`${pad}    getNextPageParam: (lastPage: ${typeAccess}['response']) => {`);
+          lines.push(`${pad}      const meta = (lastPage as any)?.meta;`);
+          lines.push(`${pad}      if (meta?.page != null && meta?.lastPage != null) {`);
+          lines.push(`${pad}        return meta.page < meta.lastPage ? meta.page + 1 : undefined;`);
+          lines.push(`${pad}      }`);
+          lines.push(`${pad}      return undefined;`);
+          lines.push(`${pad}    },`);
+          lines.push(`${pad}  }),`);
+        }
         lines.push(`${pad}},`);
       } else {
         const typeAccess = buildRouterTypeAccess(c.name);
+        const withParams = hasPathParams(c.params);
         lines.push(`${pad}${objKey}: {`);
         lines.push(`${pad}  queryKey: () => [${flatName}] as const,`);
-        lines.push(`${pad}  mutationOptions: () => ({`);
-        lines.push(`${pad}    mutationFn: (body: ${typeAccess}['body']) => fetcher.${fetcherMethod}<${typeAccess}['response']>(route(${flatName} as never) || ${safePath}, { body }),`);
-        lines.push(`${pad}  }),`);
+        lines.push(`${pad}  mutationOptions: () =>`);
+        lines.push(`${pad}    _mutationOptions({`);
+        if (withParams) {
+          lines.push(`${pad}      mutationFn: (input: { params: ${typeAccess}['params']; body: ${typeAccess}['body'] }) => fetcher.${fetcherMethod}<${typeAccess}['response']>(route(${flatName} as never, input.params as never) || ${safePath}, { body: input.body }),`);
+        } else {
+          lines.push(`${pad}      mutationFn: (body: ${typeAccess}['body']) => fetcher.${fetcherMethod}<${typeAccess}['response']>(route(${flatName} as never) || ${safePath}, { body }),`);
+        }
+        lines.push(`${pad}    }),`);
         lines.push(`${pad}},`);
       }
     } else {
@@ -362,11 +416,15 @@ function buildApiFile(routes, outDir) {
   for (const r of contracted) {
     const cs = r.contract?.contractSource;
     if (!cs) continue;
-    for (const ref of [
+    const refs = r.controllerRef ? [
+      cs.queryRef,
+      cs.bodyRef
+    ] : [
       cs.queryRef,
       cs.bodyRef,
       cs.responseRef
-    ]) {
+    ];
+    for (const ref of refs) {
       if (!ref) continue;
       let names = importsByFile.get(ref.filePath);
       if (!names) {
@@ -376,10 +434,18 @@ function buildApiFile(routes, outDir) {
       names.add(ref.name);
     }
   }
+  const hasGetRoutes = contracted.some((r) => r.method === "GET");
+  const hasMutationRoutes = contracted.some((r) => r.method !== "GET");
   const lines = [
     "// Generated by @dudousxd/nestjs-inertia-codegen. Do not edit.",
     ""
   ];
+  const tqImports = [];
+  if (hasGetRoutes) tqImports.push("queryOptions as _queryOptions");
+  if (hasMutationRoutes) tqImports.push("mutationOptions as _mutationOptions");
+  if (tqImports.length > 0) {
+    lines.push(`import { ${tqImports.join(", ")} } from '@tanstack/react-query';`);
+  }
   lines.push("import { route } from './routes.js';");
   lines.push("import { createFetcher } from '@dudousxd/nestjs-inertia-client';");
   if (importsByFile.size > 0 && outDir) {
@@ -433,13 +499,14 @@ function buildApiFile(routes, outDir) {
       method: r.method,
       name,
       path: r.path,
+      params: r.params,
+      controllerRef: r.controllerRef,
       contractSource: c.contractSource
     };
     insertIntoTree(tree, segments, leaf, name);
   }
-  void detectCollisions;
   lines.push("export type ApiRouter = {");
-  lines.push(...emitRouterTypeBlock(tree, 2));
+  lines.push(...emitRouterTypeBlock(tree, 2, outDir ?? ""));
   lines.push("};");
   lines.push("");
   lines.push("export const api = {");
@@ -536,7 +603,8 @@ __name(emitIndex, "emitIndex");
 // src/emit/emit-pages.ts
 var import_promises6 = require("fs/promises");
 var import_node_path6 = require("path");
-async function emitPages(pages, outDir) {
+async function emitPages(pages, outDir, options = {}) {
+  const propsExport = options.propsExport ?? "ComponentProps";
   await (0, import_promises6.mkdir)(outDir, {
     recursive: true
   });
@@ -545,14 +613,40 @@ async function emitPages(pages, outDir) {
     const key = needsQuotes(p.name) ? JSON.stringify(p.name) : p.name;
     return `  ${key}: ${propType};`;
   }).join("\n");
+  const pageNameUnion = pages.length > 0 ? pages.map((p) => JSON.stringify(p.name)).join(" | ") : "never";
+  const augBody = pages.map((p) => {
+    const key = needsQuotes(p.name) ? JSON.stringify(p.name) : p.name;
+    const valueType = buildAugmentationType(p, outDir, propsExport);
+    return `    ${key}: ${valueType};`;
+  }).join("\n");
+  const propsHelper = "\nexport type InertiaProps<K extends InertiaPageName> = import('@dudousxd/nestjs-inertia').InertiaPages[K];\n";
   const content = `// Generated by @dudousxd/nestjs-inertia-codegen. Do not edit.
 export interface InertiaPages {
 ${body}
 }
+
+export type InertiaPageName = ${pageNameUnion};
+` + propsHelper + `
+declare module '@dudousxd/nestjs-inertia' {
+  interface InertiaPages {
+${augBody}
+  }
+}
 `;
   await (0, import_promises6.writeFile)((0, import_node_path6.join)(outDir, "pages.d.ts"), content, "utf8");
 }
 __name(emitPages, "emitPages");
+function buildAugmentationType(page, outDir, propsExport) {
+  if (!page.propsSource) {
+    return "Record<string, unknown>";
+  }
+  let importPath = (0, import_node_path6.relative)(outDir, page.absolutePath).replace(/\.(tsx?|vue|svelte)$/, "");
+  if (!importPath.startsWith(".")) {
+    importPath = `./${importPath}`;
+  }
+  return `import('${importPath}').${propsExport}`;
+}
+__name(buildAugmentationType, "buildAugmentationType");
 function needsQuotes(name) {
   return !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
 }
@@ -689,7 +783,9 @@ async function generate(config, routes = []) {
     propsExport: config.pages.propsExport,
     componentNameStrategy: config.pages.componentNameStrategy
   });
-  await emitPages(pages, config.codegen.outDir);
+  await emitPages(pages, config.codegen.outDir, {
+    propsExport: config.pages.propsExport
+  });
   await emitCache(pages, config.codegen.outDir);
   const hasRoutes = routes.length > 0;
   const hasContracts = routes.some((r) => r.contract);
@@ -704,14 +800,43 @@ async function generate(config, routes = []) {
 __name(generate, "generate");
 
 // src/watch/watcher.ts
-var import_promises9 = require("fs/promises");
+var import_promises10 = require("fs/promises");
 var import_node_path10 = require("path");
 var import_chokidar = __toESM(require("chokidar"), 1);
 
 // src/discovery/contracts-fast.ts
+var import_node_fs = require("fs");
 var import_node_path8 = require("path");
 var import_fast_glob2 = __toESM(require("fast-glob"), 1);
 var import_ts_morph = require("ts-morph");
+var _ctx = {
+  projectRoot: "",
+  tsconfigPaths: null
+};
+function _projectRoot() {
+  return _ctx.projectRoot;
+}
+__name(_projectRoot, "_projectRoot");
+function _tsconfigPaths() {
+  return _ctx.tsconfigPaths;
+}
+__name(_tsconfigPaths, "_tsconfigPaths");
+var _debug = process.env.NESTJS_INERTIA_DEBUG === "1";
+function dbg(...args) {
+  if (_debug) console.log("[codegen:debug]", ...args);
+}
+__name(dbg, "dbg");
+function loadTsconfigPaths(tsconfigPath) {
+  try {
+    const raw = (0, import_node_fs.readFileSync)(tsconfigPath, "utf8");
+    const stripped = raw.replace(/\/\/.*$/gm, "");
+    const parsed = JSON.parse(stripped);
+    return parsed.compilerOptions?.paths ?? null;
+  } catch {
+    return null;
+  }
+}
+__name(loadTsconfigPaths, "loadTsconfigPaths");
 async function discoverContractsFast(opts) {
   const { cwd, glob, tsconfig } = opts;
   const tsconfigPath = tsconfig ? (0, import_node_path8.resolve)(tsconfig) : (0, import_node_path8.join)(cwd, "tsconfig.json");
@@ -744,8 +869,17 @@ async function discoverContractsFast(opts) {
     project.addSourceFileAtPath(f);
   }
   const routes = [];
-  for (const sourceFile of project.getSourceFiles()) {
-    routes.push(...extractFromSourceFile(sourceFile, project));
+  const prevCtx = _ctx;
+  _ctx = {
+    projectRoot: cwd,
+    tsconfigPaths: loadTsconfigPaths(tsconfigPath)
+  };
+  try {
+    for (const sourceFile of project.getSourceFiles()) {
+      routes.push(...extractFromSourceFile(sourceFile, project));
+    }
+  } finally {
+    _ctx = prevCtx;
   }
   return routes;
 }
@@ -945,17 +1079,42 @@ function findTypeInFile(name, file) {
   return null;
 }
 __name(findTypeInFile, "findTypeInFile");
+function resolveModuleSpecifier(moduleSpecifier, sourceFile, project) {
+  if (moduleSpecifier.startsWith(".")) {
+    const dir = (0, import_node_path8.dirname)(sourceFile.getFilePath());
+    return [
+      (0, import_node_path8.resolve)(dir, `${moduleSpecifier}.ts`),
+      (0, import_node_path8.resolve)(dir, moduleSpecifier, "index.ts")
+    ];
+  }
+  const baseUrl = _projectRoot();
+  const tsconfigPaths = _tsconfigPaths();
+  dbg("resolveModuleSpecifier", moduleSpecifier, "paths:", JSON.stringify(tsconfigPaths), "baseUrl:", baseUrl);
+  if (tsconfigPaths) {
+    for (const [pattern, mappings] of Object.entries(tsconfigPaths)) {
+      const prefix = pattern.replace("*", "");
+      if (moduleSpecifier.startsWith(prefix)) {
+        const rest = moduleSpecifier.slice(prefix.length);
+        const candidates = [];
+        for (const mapping of mappings) {
+          const resolved = (0, import_node_path8.resolve)(baseUrl, mapping.replace("*", rest));
+          candidates.push(`${resolved}.ts`, (0, import_node_path8.resolve)(resolved, "index.ts"));
+        }
+        dbg("  resolved candidates:", candidates);
+        return candidates;
+      }
+    }
+  }
+  return [];
+}
+__name(resolveModuleSpecifier, "resolveModuleSpecifier");
 function resolveImportedType(name, sourceFile, project) {
   for (const importDecl of sourceFile.getImportDeclarations()) {
     const namedImport = importDecl.getNamedImports().find((n) => n.getName() === name);
     if (!namedImport) continue;
     const moduleSpecifier = importDecl.getModuleSpecifierValue();
-    if (!moduleSpecifier.startsWith(".")) return null;
-    const dir = (0, import_node_path8.dirname)(sourceFile.getFilePath());
-    const candidates = [
-      (0, import_node_path8.resolve)(dir, `${moduleSpecifier}.ts`),
-      (0, import_node_path8.resolve)(dir, moduleSpecifier, "index.ts")
-    ];
+    const candidates = resolveModuleSpecifier(moduleSpecifier, sourceFile, project);
+    if (candidates.length === 0) continue;
     for (const candidate of candidates) {
       let importedFile = project.getSourceFile(candidate);
       if (!importedFile) {
@@ -999,6 +1158,18 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth) {
       }
       return "Array<unknown>";
     }
+    if ([
+      "Record",
+      "Omit",
+      "Pick",
+      "Partial",
+      "Required",
+      "Readonly",
+      "Map",
+      "Set"
+    ].includes(name)) {
+      return typeNode.getText();
+    }
     if (name === "Promise") {
       const typeArgs = typeNode.getTypeArguments();
       const firstTypeArg = typeArgs[0];
@@ -1011,7 +1182,8 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth) {
     if (resolved) {
       return expandTypeDecl(resolved, project, depth - 1);
     }
-    return name;
+    dbg("unresolvable type:", name, "in", sourceFile.getFilePath());
+    return "unknown";
   }
   const kind = typeNode.getKind();
   if (kind === import_ts_morph.SyntaxKind.StringKeyword) return "string";
@@ -1173,7 +1345,7 @@ function tryResolveTypeRef(typeNode, sourceFile, project) {
       return null;
     }
     const localDecl = sourceFile.getInterface(name) || sourceFile.getClass(name) || sourceFile.getTypeAlias(name);
-    if (localDecl && localDecl.isExported()) {
+    if (localDecl?.isExported()) {
       return {
         name,
         filePath: sourceFile.getFilePath()
@@ -1235,7 +1407,7 @@ function extractDtoContract(method, sourceFile, project) {
             if (val && import_ts_morph.Node.isIdentifier(val)) {
               const name = val.getText();
               const localDecl = sourceFile.getInterface(name) || sourceFile.getClass(name) || sourceFile.getTypeAlias(name);
-              if (localDecl && localDecl.isExported()) {
+              if (localDecl?.isExported()) {
                 responseRef = {
                   name,
                   filePath: sourceFile.getFilePath()
@@ -1361,6 +1533,11 @@ function extractFromSourceFile(sourceFile, project) {
           path: combined,
           name: routeName,
           params,
+          controllerRef: {
+            className,
+            methodName,
+            filePath: sourceFile.getFilePath()
+          },
           contract: {
             contractSource: {
               query: contractDef.query,
@@ -1395,19 +1572,21 @@ function extractFromSourceFile(sourceFile, project) {
           path: combined,
           name: routeName,
           params,
-          // Attach contract if DTO extraction produced useful type info
-          ...dtoContract ? {
-            contract: {
-              contractSource: {
-                query: dtoContract.query,
-                body: dtoContract.body,
-                response: dtoContract.response,
-                queryRef: dtoContract.queryRef,
-                bodyRef: dtoContract.bodyRef,
-                responseRef: dtoContract.responseRef
-              }
+          controllerRef: {
+            className,
+            methodName,
+            filePath: sourceFile.getFilePath()
+          },
+          contract: {
+            contractSource: {
+              query: dtoContract?.query ?? null,
+              body: dtoContract?.body ?? null,
+              response: dtoContract?.response ?? "unknown",
+              queryRef: dtoContract?.queryRef,
+              bodyRef: dtoContract?.bodyRef,
+              responseRef: dtoContract?.responseRef
             }
-          } : {}
+          }
         });
       }
     }
@@ -1418,6 +1597,7 @@ __name(extractFromSourceFile, "extractFromSourceFile");
 
 // src/watch/lock-file.ts
 var import_promises8 = require("fs/promises");
+var import_promises9 = require("fs/promises");
 var import_node_path9 = require("path");
 var LOCK_FILE = ".watcher.lock";
 function isProcessAlive(pid) {
@@ -1430,28 +1610,37 @@ function isProcessAlive(pid) {
 }
 __name(isProcessAlive, "isProcessAlive");
 async function acquireLock(outDir) {
-  await (0, import_promises8.mkdir)(outDir, {
+  await (0, import_promises9.mkdir)(outDir, {
     recursive: true
   });
   const lockPath = (0, import_node_path9.join)(outDir, LOCK_FILE);
-  try {
-    const raw = await (0, import_promises8.readFile)(lockPath, "utf8");
-    const existing = JSON.parse(raw);
-    if (isProcessAlive(existing.pid)) {
-      return null;
-    }
-  } catch {
-  }
   const lockData = {
     pid: process.pid,
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  await (0, import_promises8.writeFile)(lockPath, `${JSON.stringify(lockData, null, 2)}
+  try {
+    const fd = await (0, import_promises8.open)(lockPath, "wx");
+    await fd.writeFile(`${JSON.stringify(lockData, null, 2)}
 `, "utf8");
+    await fd.close();
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      try {
+        const raw = await (0, import_promises9.readFile)(lockPath, "utf8");
+        const existing = JSON.parse(raw);
+        if (isProcessAlive(existing.pid)) return null;
+        await (0, import_promises9.unlink)(lockPath);
+        return acquireLock(outDir);
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
   return {
     release: /* @__PURE__ */ __name(async () => {
       try {
-        await (0, import_promises8.unlink)(lockPath);
+        await (0, import_promises9.unlink)(lockPath);
       } catch {
       }
     }, "release")
@@ -1470,7 +1659,7 @@ async function watch(config, onChange) {
   if (lock === null) {
     let holderPid = "unknown";
     try {
-      const raw = await (0, import_promises9.readFile)((0, import_node_path10.join)(config.codegen.outDir, ".watcher.lock"), "utf8");
+      const raw = await (0, import_promises10.readFile)((0, import_node_path10.join)(config.codegen.outDir, ".watcher.lock"), "utf8");
       const data = JSON.parse(raw);
       if (data.pid !== void 0) holderPid = String(data.pid);
     } catch {
@@ -1511,7 +1700,8 @@ async function watch(config, onChange) {
       pagesDebounceTimer = void 0;
       try {
         await generate(config);
-      } catch {
+      } catch (err) {
+        console.error("[nestjs-inertia-codegen] Pages generation failed:", err instanceof Error ? err.message : err);
       }
       onChange?.();
     }, PAGES_DEBOUNCE_MS);
@@ -1549,7 +1739,8 @@ async function watch(config, onChange) {
         if (hasContracts) {
           await emitApi(routes, config.codegen.outDir);
         }
-      } catch {
+      } catch (err) {
+        console.error("[nestjs-inertia-codegen] Contracts generation failed:", err instanceof Error ? err.message : err);
       }
       onChange?.();
     }, config.contracts.debounceMs);
@@ -1577,7 +1768,7 @@ async function watch(config, onChange) {
 __name(watch, "watch");
 
 // src/index.ts
-var VERSION = "1.2.0";
+var VERSION = "1.4.0";
 
 // src/cli/codegen.ts
 async function runCodegen(opts = {}) {
@@ -1607,11 +1798,163 @@ async function runCodegen(opts = {}) {
 }
 __name(runCodegen, "runCodegen");
 
+// src/cli/doctor.ts
+var import_node_fs2 = require("fs");
+var import_node_path11 = require("path");
+function checkFileExists(cwd, file) {
+  return (0, import_node_fs2.existsSync)((0, import_node_path11.join)(cwd, file));
+}
+__name(checkFileExists, "checkFileExists");
+function readJson(path) {
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(path, "utf8").replace(/\/\/.*$/gm, "");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+__name(readJson, "readJson");
+function getPackageVersion(cwd, pkg) {
+  try {
+    const pkgJson = readJson((0, import_node_path11.join)(cwd, "node_modules", pkg, "package.json"));
+    return pkgJson?.version ?? null;
+  } catch {
+    return null;
+  }
+}
+__name(getPackageVersion, "getPackageVersion");
+async function runDoctor(opts) {
+  const { cwd } = opts;
+  const checks = [];
+  checks.push({
+    name: "nestjs-inertia.config.ts exists",
+    pass: checkFileExists(cwd, "nestjs-inertia.config.ts"),
+    fix: "Run: pnpm exec nestjs-inertia init"
+  });
+  const hasApi = checkFileExists(cwd, ".nestjs-inertia/api.ts");
+  const hasRoutes = checkFileExists(cwd, ".nestjs-inertia/routes.ts");
+  const hasPages = checkFileExists(cwd, ".nestjs-inertia/pages.d.ts");
+  checks.push({
+    name: ".nestjs-inertia/ codegen output exists",
+    pass: hasApi && hasRoutes && hasPages,
+    fix: "Run: pnpm exec nestjs-inertia codegen"
+  });
+  const tsconfig = readJson((0, import_node_path11.join)(cwd, "tsconfig.json"));
+  const paths = tsconfig?.compilerOptions?.paths;
+  checks.push({
+    name: "tsconfig.json has @/* path alias",
+    pass: !!paths?.["@/*"],
+    fix: 'Add to tsconfig.json compilerOptions.paths: { "@/*": ["./src/*"] }'
+  });
+  const inertiaTsconfig = readJson((0, import_node_path11.join)(cwd, "tsconfig.inertia.json"));
+  if (inertiaTsconfig) {
+    const inertiaPaths = inertiaTsconfig.compilerOptions?.paths;
+    checks.push({
+      name: "tsconfig.inertia.json has ~/* and ~codegen/* aliases",
+      pass: !!inertiaPaths?.["~/*"] && !!inertiaPaths?.["~codegen/*"],
+      fix: 'Add paths: { "~/*": ["inertia/*"], "~codegen/*": [".nestjs-inertia/*"] }'
+    });
+  }
+  if (checkFileExists(cwd, "vite.config.ts")) {
+    const viteContent = (0, import_node_fs2.readFileSync)((0, import_node_path11.join)(cwd, "vite.config.ts"), "utf8");
+    checks.push({
+      name: "vite.config.ts has resolve.alias",
+      pass: viteContent.includes("resolve") && viteContent.includes("alias"),
+      fix: "Add resolve.alias with @\u2192src, ~\u2192inertia, ~codegen\u2192.nestjs-inertia"
+    });
+    checks.push({
+      name: "vite.config.ts references nestjs-inertia",
+      pass: viteContent.includes("nestInertia") || viteContent.includes("nestjs-inertia") || viteContent.includes("setupInertiaVite"),
+      fix: "Add: import nestInertia from '@dudousxd/nestjs-inertia-vite/plugin'"
+    });
+  }
+  const libPackages = [
+    "@dudousxd/nestjs-inertia",
+    "@dudousxd/nestjs-inertia-codegen",
+    "@dudousxd/nestjs-inertia-client",
+    "@dudousxd/nestjs-inertia-vite",
+    "@dudousxd/nestjs-inertia-testing"
+  ];
+  const versions = libPackages.map((pkg) => ({
+    pkg,
+    version: getPackageVersion(cwd, pkg)
+  }));
+  const installed = versions.filter((v) => v.version !== null);
+  const uniqueVersions = new Set(installed.map((v) => v.version));
+  const requiredPkgs = [
+    "@dudousxd/nestjs-inertia",
+    "@dudousxd/nestjs-inertia-codegen",
+    "@dudousxd/nestjs-inertia-client"
+  ];
+  const missingRequired = requiredPkgs.filter((pkg) => !getPackageVersion(cwd, pkg));
+  checks.push({
+    name: "Core packages installed (core + codegen + client)",
+    pass: missingRequired.length === 0,
+    fix: missingRequired.length > 0 ? `Missing: ${missingRequired.join(", ")}` : void 0
+  });
+  if (installed.length > 1) {
+    checks.push({
+      name: "All packages on same version",
+      pass: uniqueVersions.size === 1,
+      fix: `Versions: ${installed.map((v) => `${v.pkg.replace("@dudousxd/", "")}@${v.version}`).join(", ")}`
+    });
+  }
+  const inertiaReact = getPackageVersion(cwd, "@inertiajs/react");
+  const inertiaVue = getPackageVersion(cwd, "@inertiajs/vue3");
+  const inertiaSvelte = getPackageVersion(cwd, "@inertiajs/svelte");
+  const inertiaVersion = inertiaReact ?? inertiaVue ?? inertiaSvelte;
+  const inertiaFramework = inertiaReact ? "react" : inertiaVue ? "vue" : inertiaSvelte ? "svelte" : null;
+  if (inertiaVersion) {
+    const majorVersion = Number.parseInt(inertiaVersion.split(".")[0] ?? "0", 10);
+    checks.push({
+      name: `@inertiajs/${inertiaFramework} is v3+`,
+      pass: majorVersion >= 3,
+      fix: `Current: v${inertiaVersion}. Run: pnpm add @inertiajs/${inertiaFramework}@^3.0.0`
+    });
+  }
+  if (checkFileExists(cwd, ".gitignore")) {
+    const gitignore = (0, import_node_fs2.readFileSync)((0, import_node_path11.join)(cwd, ".gitignore"), "utf8");
+    checks.push({
+      name: ".gitignore includes .nestjs-inertia/",
+      pass: gitignore.includes(".nestjs-inertia"),
+      fix: "Add .nestjs-inertia/ to .gitignore"
+    });
+  }
+  const pkgJson = readJson((0, import_node_path11.join)(cwd, "package.json"));
+  const scripts = pkgJson?.scripts ?? {};
+  checks.push({
+    name: "package.json has build:client script",
+    pass: !!scripts["build:client"],
+    fix: 'Add: "build:client": "vite build"'
+  });
+  console.log("");
+  console.log("\x1B[1mnestjs-inertia doctor\x1B[0m");
+  console.log("");
+  let hasFailures = false;
+  for (const check of checks) {
+    const icon = check.pass ? "\x1B[32m\u2713\x1B[0m" : "\x1B[31m\u2717\x1B[0m";
+    console.log(`  ${icon} ${check.name}`);
+    if (!check.pass && check.fix) {
+      console.log(`    \x1B[2m${check.fix}\x1B[0m`);
+      hasFailures = true;
+    }
+  }
+  console.log("");
+  if (hasFailures) {
+    console.log(`\x1B[33m${checks.filter((c) => !c.pass).length} issue(s) found\x1B[0m`);
+  } else {
+    console.log("\x1B[32mAll checks passed!\x1B[0m");
+  }
+  console.log("");
+  return hasFailures ? 1 : 0;
+}
+__name(runDoctor, "runDoctor");
+
 // src/cli/init.ts
 var import_node_child_process = require("child_process");
-var import_node_fs = require("fs");
-var import_promises10 = require("fs/promises");
-var import_node_path11 = require("path");
+var import_node_fs3 = require("fs");
+var import_promises11 = require("fs/promises");
+var import_node_path12 = require("path");
 var import_node_readline = require("readline");
 var GITIGNORE_ENTRY = ".nestjs-inertia/";
 var green = /* @__PURE__ */ __name((s) => `\x1B[32m${s}\x1B[0m`, "green");
@@ -1642,7 +1985,7 @@ ${bold(title)}`);
 __name(logSection, "logSection");
 async function readPackageJson(cwd) {
   try {
-    const raw = await (0, import_promises10.readFile)((0, import_node_path11.join)(cwd, "package.json"), "utf8");
+    const raw = await (0, import_promises11.readFile)((0, import_node_path12.join)(cwd, "package.json"), "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -1680,7 +2023,7 @@ __name(detectTemplateEngine, "detectTemplateEngine");
 async function detectPackageManager(cwd) {
   async function exists(file) {
     try {
-      await (0, import_promises10.access)((0, import_node_path11.join)(cwd, file));
+      await (0, import_promises11.access)((0, import_node_path12.join)(cwd, file));
       return true;
     } catch {
       return false;
@@ -1711,7 +2054,7 @@ async function promptFramework() {
 __name(promptFramework, "promptFramework");
 async function fileExists2(filePath) {
   try {
-    await (0, import_promises10.access)(filePath);
+    await (0, import_promises11.access)(filePath);
     return true;
   } catch {
     return false;
@@ -1725,18 +2068,18 @@ async function writeIfNotExists(filePath, content, label) {
   }
   const dir = filePath.substring(0, filePath.lastIndexOf("/"));
   if (dir) {
-    await (0, import_promises10.mkdir)(dir, {
+    await (0, import_promises11.mkdir)(dir, {
       recursive: true
     });
   }
-  await (0, import_promises10.writeFile)(filePath, content, "utf8");
+  await (0, import_promises11.writeFile)(filePath, content, "utf8");
   logCreated(label);
 }
 __name(writeIfNotExists, "writeIfNotExists");
 async function handleViteConfig(cwd, framework) {
-  const filePath = (0, import_node_path11.join)(cwd, "vite.config.ts");
+  const filePath = (0, import_node_path12.join)(cwd, "vite.config.ts");
   if (await fileExists2(filePath)) {
-    const existing = await (0, import_promises10.readFile)(filePath, "utf8");
+    const existing = await (0, import_promises11.readFile)(filePath, "utf8");
     const hasPlugin = existing.includes("nestInertia") || existing.includes("nestjs-inertia-vite/plugin");
     if (!hasPlugin) {
       logSkipped("vite.config.ts");
@@ -1750,18 +2093,18 @@ async function handleViteConfig(cwd, framework) {
   }
   const dir = filePath.substring(0, filePath.lastIndexOf("/"));
   if (dir) {
-    await (0, import_promises10.mkdir)(dir, {
+    await (0, import_promises11.mkdir)(dir, {
       recursive: true
     });
   }
-  await (0, import_promises10.writeFile)(filePath, viteConfigTemplate(framework), "utf8");
+  await (0, import_promises11.writeFile)(filePath, viteConfigTemplate(framework), "utf8");
   logCreated("vite.config.ts");
 }
 __name(handleViteConfig, "handleViteConfig");
 async function patchGitignore(gitignorePath) {
   let existing = "";
   if (await fileExists2(gitignorePath)) {
-    existing = await (0, import_promises10.readFile)(gitignorePath, "utf8");
+    existing = await (0, import_promises11.readFile)(gitignorePath, "utf8");
   }
   if (existing.split("\n").some((line) => line.trim() === GITIGNORE_ENTRY)) {
     console.log(`  ${cyan("\u2192")} .gitignore ${dim("(already contains .nestjs-inertia/, skipped)")}`);
@@ -1771,30 +2114,36 @@ async function patchGitignore(gitignorePath) {
 ` : `${existing}
 ${GITIGNORE_ENTRY}
 `;
-  await (0, import_promises10.writeFile)(gitignorePath, newContent, "utf8");
+  await (0, import_promises11.writeFile)(gitignorePath, newContent, "utf8");
   logPatched(".gitignore", "added .nestjs-inertia/");
 }
 __name(patchGitignore, "patchGitignore");
 function installDeps(pkgManager, deps, dev) {
   if (deps.length === 0) return;
-  const flag = dev ? pkgManager === "npm" ? "--save-dev" : "-D" : "";
-  const cmd = pkgManager === "npm" ? `npm install ${flag} ${deps.join(" ")}` : pkgManager === "yarn" ? `yarn add ${flag} ${deps.join(" ")}` : `pnpm add ${flag} ${deps.join(" ")}`;
+  const args = [];
+  if (pkgManager === "npm") {
+    args.push("install");
+    if (dev) args.push("--save-dev");
+  } else {
+    args.push("add");
+    if (dev) args.push("-D");
+  }
+  args.push(...deps);
   logPatched(deps.join(", "), "installed");
   try {
-    (0, import_node_child_process.execSync)(cmd, {
+    (0, import_node_child_process.execFileSync)(pkgManager, args, {
       stdio: "inherit"
     });
   } catch {
-    logWarning(`Failed to install deps. Run manually:
-    ${cmd}`);
+    logWarning(`Failed to install: ${deps.join(", ")}`);
   }
 }
 __name(installDeps, "installDeps");
 async function patchPackageJsonScripts(cwd, scripts) {
-  const pkgPath = (0, import_node_path11.join)(cwd, "package.json");
+  const pkgPath = (0, import_node_path12.join)(cwd, "package.json");
   let pkg = {};
   try {
-    pkg = JSON.parse(await (0, import_promises10.readFile)(pkgPath, "utf8"));
+    pkg = JSON.parse(await (0, import_promises11.readFile)(pkgPath, "utf8"));
   } catch {
     return;
   }
@@ -1813,7 +2162,7 @@ async function patchPackageJsonScripts(cwd, scripts) {
     return;
   }
   pkg.scripts = existing;
-  await (0, import_promises10.writeFile)(pkgPath, `${JSON.stringify(pkg, null, 2)}
+  await (0, import_promises11.writeFile)(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf8");
 }
 __name(patchPackageJsonScripts, "patchPackageJsonScripts");
@@ -1833,7 +2182,7 @@ __name(findAfterLastImport, "findAfterLastImport");
 function patchAppModule(filePath, rootView) {
   let content;
   try {
-    content = (0, import_node_fs.readFileSync)(filePath, "utf8");
+    content = (0, import_node_fs3.readFileSync)(filePath, "utf8");
   } catch {
     return "skipped";
   }
@@ -1871,14 +2220,14 @@ ${indent}HomeController,${content.slice(bracketPos)}`;
     }
   }
   if (!changed) return "already";
-  (0, import_node_fs.writeFileSync)(filePath, content, "utf8");
+  (0, import_node_fs3.writeFileSync)(filePath, content, "utf8");
   return "patched";
 }
 __name(patchAppModule, "patchAppModule");
 function patchMainTs(filePath) {
   let content;
   try {
-    content = (0, import_node_fs.readFileSync)(filePath, "utf8");
+    content = (0, import_node_fs3.readFileSync)(filePath, "utf8");
   } catch {
     return "skipped";
   }
@@ -1902,7 +2251,7 @@ ${content.slice(insertAt)}`;
   });`;
   content = `${content.slice(0, insertAfterPos)}
 ${viteSetup}${content.slice(insertAfterPos)}`;
-  (0, import_node_fs.writeFileSync)(filePath, content, "utf8");
+  (0, import_node_fs3.writeFileSync)(filePath, content, "utf8");
   return "patched";
 }
 __name(patchMainTs, "patchMainTs");
@@ -1951,11 +2300,19 @@ function htmlShellTemplate(framework, _engine) {
 __name(htmlShellTemplate, "htmlShellTemplate");
 function viteConfigTemplate(framework) {
   const pluginOption = `{ ${framework}: true }`;
-  return `import { defineConfig } from 'vite';
+  return `import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
 import nestInertia from '@dudousxd/nestjs-inertia-vite/plugin';
 
 export default defineConfig({
   plugins: [nestInertia(${pluginOption})],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+      '~': resolve(__dirname, 'inertia'),
+      '~codegen': resolve(__dirname, '.nestjs-inertia'),
+    },
+  },
 });
 `;
 }
@@ -2075,16 +2432,16 @@ ${bold("nestjs-inertia init")}`);
   const entryExt = framework === "react" ? "tsx" : "ts";
   const pageExt = framework === "react" ? "tsx" : framework === "vue" ? "vue" : "svelte";
   logSection("Scaffold files");
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "nestjs-inertia.config.ts"), configTemplate(framework), "nestjs-inertia.config.ts");
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "nestjs-inertia.d.ts"), DTS_TEMPLATE, "nestjs-inertia.d.ts");
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "inertia", shellFileName), htmlShellTemplate(framework, engine), `inertia/${shellFileName}`);
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "nestjs-inertia.config.ts"), configTemplate(framework), "nestjs-inertia.config.ts");
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "nestjs-inertia.d.ts"), DTS_TEMPLATE, "nestjs-inertia.d.ts");
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "inertia", shellFileName), htmlShellTemplate(framework, engine), `inertia/${shellFileName}`);
   await handleViteConfig(cwd, framework);
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "inertia", `app.${entryExt}`), entryPointTemplate(framework), `inertia/app.${entryExt}`);
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "inertia", "pages", `Home.${pageExt}`), samplePageTemplate(framework), `inertia/pages/Home.${pageExt}`);
-  await writeIfNotExists((0, import_node_path11.join)(cwd, "src", "home.controller.ts"), SAMPLE_CONTROLLER, "src/home.controller.ts");
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "inertia", `app.${entryExt}`), entryPointTemplate(framework), `inertia/app.${entryExt}`);
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "inertia", "pages", `Home.${pageExt}`), samplePageTemplate(framework), `inertia/pages/Home.${pageExt}`);
+  await writeIfNotExists((0, import_node_path12.join)(cwd, "src", "home.controller.ts"), SAMPLE_CONTROLLER, "src/home.controller.ts");
   logSection("Patch existing files");
   const rootView = engine === "html" ? "inertia/index.html" : `inertia/index.${engine === "handlebars" ? "hbs" : engine}`;
-  const appModulePath = (0, import_node_path11.join)(cwd, "src", "app.module.ts");
+  const appModulePath = (0, import_node_path12.join)(cwd, "src", "app.module.ts");
   const appModuleResult = patchAppModule(appModulePath, rootView);
   if (appModuleResult === "patched") {
     logPatched("src/app.module.ts", "added InertiaModule.forRoot");
@@ -2094,7 +2451,7 @@ ${bold("nestjs-inertia init")}`);
   } else {
     logWarning("src/app.module.ts not found \u2014 add InertiaModule.forRoot() manually");
   }
-  const mainTsPath = (0, import_node_path11.join)(cwd, "src", "main.ts");
+  const mainTsPath = (0, import_node_path12.join)(cwd, "src", "main.ts");
   const mainTsResult = patchMainTs(mainTsPath);
   if (mainTsResult === "patched") {
     logPatched("src/main.ts", "added setupInertiaVite after NestFactory.create");
@@ -2103,7 +2460,7 @@ ${bold("nestjs-inertia init")}`);
   } else {
     logWarning("src/main.ts not found \u2014 add setupInertiaVite() manually");
   }
-  await patchGitignore((0, import_node_path11.join)(cwd, ".gitignore"));
+  await patchGitignore((0, import_node_path12.join)(cwd, ".gitignore"));
   await patchPackageJsonScripts(cwd, {
     "build:client": "vite build",
     "build:ssr": "VITE_SSR=1 vite build --ssr"
@@ -2180,6 +2537,12 @@ async function run(argv) {
       cwd: process.cwd()
     });
   });
+  cli.command("doctor", "Diagnose your nestjs-inertia setup").action(async () => {
+    const code = await runDoctor({
+      cwd: process.cwd()
+    });
+    process.exitCode = code;
+  });
   cli.help();
   cli.version(VERSION);
   try {