@qodfy/core 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 type IssueSeverity = "critical" | "warning" | "info";
+type IssueCategory = "security" | "environment" | "api" | "webhook" | "ai" | "maintainability" | "project";
 type Issue = {
+    id: string;
+    ruleId: string;
+    category: IssueCategory;
     severity: IssueSeverity;
     title: string;
     message: string;
     file?: string;
     suggestion?: string;
+    fixPrompt?: string;
 };
 type ScanReport = {
     projectPath: string;
@@ -21,4 +26,4 @@ type ScanReport = {
 };
 declare function scanProject(projectPath: string): Promise<ScanReport>;
 
-export { type Issue, type IssueSeverity, type ScanReport, scanProject };
+export { type Issue, type IssueCategory, type IssueSeverity, type ScanReport, scanProject };

package/dist/index.js

@@ -88,37 +88,64 @@ var hardcodedSecretPatterns = [
 var LARGE_FILE_WARNING_BYTES = 40 * 1024;
 var LARGE_FILE_REPORT_LIMIT = 10;
 var MAX_FILE_SIZE_BYTES = 500 * 1024;
+var issueIdPrefixes = {
+  "project-missing-package-json": "project-missing-package-json",
+  "project-invalid-package-json": "project-invalid-package-json",
+  "project-next-not-detected": "project-next-not-detected",
+  "project-missing-readme": "project-missing-readme",
+  "environment-missing-env-example": "environment-missing-env-example",
+  "environment-variable-missing-from-example": "environment-variable-missing-from-example",
+  "security-client-side-secret": "security-client-side-secret",
+  "security-hardcoded-secret": "security-hardcoded-secret",
+  "api-route-missing-auth": "security-api-auth",
+  "ai-route-missing-rate-limit": "ai-route-rate-limit",
+  "maintainability-large-file": "maintainability-large-file",
+  "maintainability-large-file-skipped": "maintainability-large-file-skipped",
+  "maintainability-file-unreadable": "maintainability-file-unreadable",
+  "project-source-files-unreadable": "project-source-files-unreadable",
+  "webhook-missing-signature-verification": "webhook-signature-verification"
+};
 async function scanProject(projectPath) {
   const startTime = Date.now();
   const resolvedProjectPath = path.resolve(projectPath);
   const issues = [];
+  const addIssue = createIssueFactory(issues);
   const packageJsonPath = path.join(resolvedProjectPath, "package.json");
   const hasPackageJson = await fileExists(packageJsonPath);
   let isNextProject = false;
   if (!hasPackageJson) {
-    issues.push({
+    addIssue({
+      ruleId: "project-missing-package-json",
+      category: "project",
       severity: "critical",
       title: "Missing package.json",
       message: "Qodfy could not find a package.json file in this project.",
-      suggestion: "Run Qodfy from the project root or pass --path to the app folder."
+      suggestion: "Run Qodfy from the project root or pass --path to the app folder.",
+      fixPrompt: createProjectRootFixPrompt()
     });
   } else {
     const packageJsonResult = await safeReadJson(packageJsonPath);
     if (!packageJsonResult.ok) {
-      issues.push({
+      addIssue({
+        ruleId: "project-invalid-package-json",
+        category: "project",
         severity: "critical",
         title: "Could not read package.json",
         message: packageJsonResult.reason,
         file: "package.json",
-        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies."
+        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies.",
+        fixPrompt: createPackageJsonFixPrompt()
       });
     } else if (!isPackageJsonObject(packageJsonResult.data)) {
-      issues.push({
+      addIssue({
+        ruleId: "project-invalid-package-json",
+        category: "project",
         severity: "critical",
         title: "Invalid package.json",
         message: "package.json must contain a JSON object at the top level.",
         file: "package.json",
-        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies."
+        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies.",
+        fixPrompt: createPackageJsonFixPrompt()
       });
     } else {
       const deps = {
@@ -127,11 +154,14 @@ async function scanProject(projectPath) {
       };
       isNextProject = Boolean(deps.next);
       if (!isNextProject) {
-        issues.push({
+        addIssue({
+          ruleId: "project-next-not-detected",
+          category: "project",
           severity: "warning",
           title: "Next.js not detected",
           message: "This first version of Qodfy is optimized for Next.js projects.",
-          suggestion: "If this is a monorepo, scan the Next.js app folder directly."
+          suggestion: "If this is a monorepo, scan the Next.js app folder directly.",
+          fixPrompt: createNextNotDetectedFixPrompt()
         });
       }
     }
@@ -140,21 +170,27 @@ async function scanProject(projectPath) {
   const hasEnvExample = await fileExists(envExamplePath);
   let envExampleVariables = null;
   if (!hasEnvExample) {
-    issues.push({
+    addIssue({
+      ruleId: "environment-missing-env-example",
+      category: "environment",
       severity: "warning",
       title: "Missing .env.example",
       message: "Add a .env.example file so future developers know which environment variables are required.",
-      suggestion: "Document required variable names only, never real secret values."
+      suggestion: "Document required variable names only, never real secret values.",
+      fixPrompt: createMissingEnvExampleFixPrompt()
     });
   } else {
     const envExampleResult = await safeReadFile(envExamplePath);
     if (!envExampleResult.ok) {
-      issues.push({
+      addIssue({
+        ruleId: "environment-missing-env-example",
+        category: "environment",
         severity: "warning",
         title: "Could not read .env.example",
         message: envExampleResult.reason,
         file: ".env.example",
-        suggestion: "Make sure .env.example is readable and contains variable names without real secret values."
+        suggestion: "Make sure .env.example is readable and contains variable names without real secret values.",
+        fixPrompt: createMissingEnvExampleFixPrompt()
       });
     } else {
       envExampleVariables = getEnvExampleVariables(envExampleResult.content);
@@ -162,13 +198,16 @@ async function scanProject(projectPath) {
   }
   const hasReadme = await fileExists(path.join(resolvedProjectPath, "README.md"));
   if (!hasReadme) {
-    issues.push({
+    addIssue({
+      ruleId: "project-missing-readme",
+      category: "project",
       severity: "info",
       title: "Missing README.md",
-      message: "A README helps other developers understand how to run and maintain the project."
+      message: "A README helps other developers understand how to run and maintain the project.",
+      fixPrompt: createReadmeFixPrompt()
     });
   }
-  const files = await getSourceFiles(resolvedProjectPath, issues);
+  const files = await getSourceFiles(resolvedProjectPath, addIssue);
   const apiRoutes = files.filter((file) => {
     return isApiRoute(file);
   });
@@ -183,32 +222,41 @@ async function scanProject(projectPath) {
     const relativeFile = normalizePath(path.relative(resolvedProjectPath, file));
     const statResult = await safeStatFile(file);
     if (!statResult.ok) {
-      issues.push({
+      addIssue({
+        ruleId: "maintainability-file-unreadable",
+        category: "maintainability",
         severity: "info",
         title: "File could not be checked",
         message: statResult.reason,
-        file: relativeFile
+        file: relativeFile,
+        suggestion: "Check file permissions if this file should be included in launch-readiness scans."
       });
       continue;
     }
     if (statResult.size > MAX_FILE_SIZE_BYTES) {
       largeFiles++;
-      issues.push({
+      addIssue({
+        ruleId: "maintainability-large-file-skipped",
+        category: "maintainability",
         severity: "info",
         title: "Large file skipped from deep scan",
         message: "This file is larger than 500KB and was skipped from deep content checks.",
         file: relativeFile,
-        suggestion: "Review large generated or bundled files manually."
+        suggestion: "Review large generated or bundled files manually.",
+        fixPrompt: createLargeFileFixPrompt(relativeFile)
       });
       continue;
     }
     const fileResult = await safeReadFile(file);
     if (!fileResult.ok) {
-      issues.push({
+      addIssue({
+        ruleId: "maintainability-file-unreadable",
+        category: "maintainability",
         severity: "info",
         title: "File could not be read",
         message: fileResult.reason,
-        file: relativeFile
+        file: relativeFile,
+        suggestion: "Check file permissions if this file should be included in launch-readiness scans."
       });
       continue;
     }
@@ -227,35 +275,29 @@ async function scanProject(projectPath) {
       aiFiles++;
       const hasRateLimit = content.includes("rateLimit") || content.includes("ratelimit") || content.includes("upstash") || content.includes("limiter");
       if (apiRouteSet.has(file) && !hasRateLimit) {
-        issues.push({
+        addIssue({
+          ruleId: "ai-route-missing-rate-limit",
+          category: "ai",
           severity: "critical",
           title: "AI route may be missing rate limiting",
           message: "AI routes can create real API costs. Add rate limiting or usage limits before launch.",
           file: relativeFile,
-          suggestion: "Add rate limiting, usage limits, or per-user quotas before launch."
+          suggestion: "Add rate limiting, usage limits, or per-user quotas before launch.",
+          fixPrompt: createAiRateLimitFixPrompt(relativeFile)
         });
       }
     }
-    const isStripeWebhook = isStripeWebhookRoute(relativeFile, content);
-    const hasStripeSignatureVerification = hasStripeWebhookSignatureVerification(content);
-    const isClerkWebhook = isClerkWebhookRoute(relativeFile, content);
-    const hasClerkSignatureVerification = hasClerkWebhookSignatureVerification(content);
-    if (isStripeWebhook && !hasStripeSignatureVerification) {
-      issues.push({
-        severity: "critical",
-        title: "Stripe webhook may be missing signature verification",
-        message: "This Stripe webhook route does not appear to verify the Stripe signature before handling the event.",
-        file: relativeFile,
-        suggestion: "Use stripe.webhooks.constructEvent with the raw request body, Stripe-Signature header, and STRIPE_WEBHOOK_SECRET."
-      });
-    }
-    if (isClerkWebhook && !hasClerkSignatureVerification) {
-      issues.push({
-        severity: "critical",
-        title: "Clerk webhook may be missing signature verification",
-        message: "This Clerk webhook route does not appear to verify the webhook signature before handling the event.",
+    const webhookRouteInfo = apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
+    if (webhookRouteInfo && !hasWebhookSignatureVerification(content, webhookRouteInfo.provider)) {
+      addIssue({
+        ruleId: "webhook-missing-signature-verification",
+        category: "webhook",
+        severity: webhookRouteInfo.confidence === "high" ? "critical" : "warning",
+        title: "Webhook route may be missing signature verification",
+        message: "This webhook route appears to handle external events, but Qodfy could not find signature verification before the event is handled.",
         file: relativeFile,
-        suggestion: "Use svix Webhook(...).verify(...) with CLERK_WEBHOOK_SECRET and Clerk webhook headers."
+        suggestion: getWebhookSignatureSuggestion(webhookRouteInfo.provider),
+        fixPrompt: createWebhookSignatureFixPrompt(relativeFile)
       });
     }
     for (const secretMatch of getHardcodedSecretMatches(content)) {
@@ -264,23 +306,29 @@ async function scanProject(projectPath) {
         continue;
       }
       hardcodedSecretWarningKeys.add(warningKey);
-      issues.push({
+      addIssue({
+        ruleId: "security-hardcoded-secret",
+        category: "security",
         severity: "critical",
         title: "Possible hardcoded secret",
         message: `A string literal in ${relativeFile} matches the pattern for ${secretMatch.label}. Qodfy does not print possible secret values.`,
         file: relativeFile,
-        suggestion: "Move secrets into environment variables and rotate the value if this is a real secret."
+        suggestion: "Move secrets into environment variables and rotate the value if this is a real secret.",
+        fixPrompt: createHardcodedSecretFixPrompt(relativeFile, secretMatch.label)
       });
     }
     if (apiRouteSet.has(file)) {
       const hasAuth = content.includes("auth(") || content.includes("getServerSession") || content.includes("currentUser") || content.includes("clerkClient") || content.includes("session");
-      if (!hasAuth && !isStripeWebhook && !isClerkWebhook) {
-        issues.push({
+      if (!hasAuth && !webhookRouteInfo) {
+        addIssue({
+          ruleId: "api-route-missing-auth",
+          category: "api",
           severity: "warning",
           title: "API route may be missing authentication",
           message: "This API route does not appear to contain an auth/session check.",
           file: relativeFile,
-          suggestion: "Confirm the route is public, or add an auth/session check before handling user data."
+          suggestion: "Confirm the route is public, or add an auth/session check before handling user data.",
+          fixPrompt: createApiAuthFixPrompt(relativeFile)
         });
       }
     }
@@ -303,34 +351,43 @@ async function scanProject(projectPath) {
             continue;
           }
           clientSecretWarningKeys.add(warningKey);
-          issues.push({
+          addIssue({
+            ruleId: "security-client-side-secret",
+            category: "security",
             severity: "warning",
             title: "Possible server secret used in client-side code",
             message: `${variableName} appears in a client-side file. Server secrets should not be exposed to the browser.`,
             file: relativeFile,
-            suggestion: "Move server-only environment variable access to a server component, API route, or server action."
+            suggestion: "Move server-only environment variable access to a server component, API route, or server action.",
+            fixPrompt: createClientSideSecretFixPrompt(relativeFile, variableName)
           });
         }
       }
     }
   }
   for (const largeFile of getReportedLargeFiles(largeFileCandidates)) {
-    issues.push({
+    addIssue({
+      ruleId: "maintainability-large-file",
+      category: "maintainability",
       severity: "info",
       title: "Large file detected",
-      message: "Large files are harder to maintain and often appear in AI-generated codebases.",
+      message: "This file is larger than the recommended maintainability threshold. Large files can be harder to review, test, and safely modify.",
       file: largeFile.relativeFile,
-      suggestion: "Consider splitting this file into smaller modules if it mixes unrelated responsibilities."
+      suggestion: "Review whether this file mixes UI, state, data fetching, validation, or business logic. If so, split it into smaller components, hooks, or utilities.",
+      fixPrompt: createLargeFileFixPrompt(largeFile.relativeFile)
     });
   }
   for (const [variableName, filesUsingVariable] of getSortedMissingEnvUsages(missingEnvUsages)) {
     const files2 = [...filesUsingVariable].sort();
-    issues.push({
+    addIssue({
+      ruleId: "environment-variable-missing-from-example",
+      category: "environment",
       severity: "warning",
       title: "Environment variable missing from .env.example",
       message: getMissingEnvMessage(variableName, files2),
       file: files2.length === 1 ? files2[0] : void 0,
-      suggestion: `Add ${variableName}= to .env.example without including a real value.`
+      suggestion: `Add ${variableName}= to .env.example without including a real value.`,
+      fixPrompt: createMissingEnvVariableFixPrompt(variableName, files2)
     });
   }
   const criticalCount = issues.filter((issue) => issue.severity === "critical").length;
@@ -351,6 +408,20 @@ async function scanProject(projectPath) {
     }
   };
 }
+function createIssueFactory(issues) {
+  const issueCounts = /* @__PURE__ */ new Map();
+  return (issue) => {
+    const currentCount = (issueCounts.get(issue.ruleId) ?? 0) + 1;
+    issueCounts.set(issue.ruleId, currentCount);
+    issues.push({
+      id: `${getIssueIdPrefix(issue.ruleId, issue.category)}-${currentCount}`,
+      ...issue
+    });
+  };
+}
+function getIssueIdPrefix(ruleId, category) {
+  return issueIdPrefixes[ruleId] ?? `${category}-${ruleId}`;
+}
 async function fileExists(filePath) {
   try {
     await fs.access(filePath);
@@ -435,7 +506,7 @@ async function safeReadJson(filePath) {
     };
   }
 }
-async function getSourceFiles(projectPath, issues) {
+async function getSourceFiles(projectPath, addIssue) {
   try {
     return await fg(sourceFilePatterns, {
       cwd: projectPath,
@@ -445,11 +516,14 @@ async function getSourceFiles(projectPath, issues) {
       dot: false
     });
   } catch {
-    issues.push({
+    addIssue({
+      ruleId: "project-source-files-unreadable",
+      category: "project",
       severity: "critical",
       title: "Could not scan source files",
       message: "Qodfy could not list source files in this project.",
-      suggestion: "Check that the project path exists and is readable."
+      suggestion: "Check that the project path exists and is readable.",
+      fixPrompt: createProjectRootFixPrompt()
     });
     return [];
   }
@@ -536,23 +610,300 @@ function isClientSideFile(relativeFile, content) {
   return fileName.includes(".client.") || /(^|\n)\s*["']use client["'];?/.test(content);
 }
 function isApiRoute(filePath) {
-  return filePath.includes(`${path.sep}app${path.sep}api${path.sep}`) || filePath.includes(`${path.sep}pages${path.sep}api${path.sep}`);
+  const normalizedFile = normalizePath(filePath);
+  const sourceFileExtension = "(?:ts|tsx|js|jsx|mts|cts|mjs|cjs)";
+  return new RegExp(`/app/api(?:/.+)?/route\\.${sourceFileExtension}$`).test(normalizedFile) || new RegExp(`/pages/api/.+\\.${sourceFileExtension}$`).test(normalizedFile);
 }
-function isStripeWebhookRoute(relativeFile, content) {
+function getWebhookRouteInfo(relativeFile, content) {
   const normalizedFile = relativeFile.toLowerCase();
   const normalizedContent = content.toLowerCase();
-  return normalizedContent.includes("stripe") && (normalizedFile.includes("webhook") || normalizedContent.includes("webhook") || normalizedContent.includes("stripe.webhooks"));
+  const normalizedRouteContext = `${normalizedFile}
+${normalizedContent}`;
+  const pathLooksLikeWebhook = normalizedFile.includes("webhook") || normalizedFile.includes("callback");
+  const contentStronglySuggestsWebhook = normalizedContent.includes("stripe.webhooks") || normalizedContent.includes("constructevent(") || normalizedContent.includes("stripe-signature") || normalizedContent.includes("stripe_webhook_secret") || normalizedContent.includes("clerk_webhook_secret") || normalizedContent.includes("svix") || normalizedContent.includes("x-github-event") || normalizedContent.includes("x-hub-signature") || normalizedContent.includes("x-shopify-hmac-sha256") || normalizedContent.includes("resend") && normalizedContent.includes("webhook") || normalizedContent.includes("webhook_secret") || normalizedContent.includes("webhooksecret") || normalizedContent.includes("webhook") && (normalizedContent.includes("signature") || normalizedContent.includes("secret") || normalizedContent.includes("event"));
+  if (!pathLooksLikeWebhook && !contentStronglySuggestsWebhook) {
+    return null;
+  }
+  const provider = getWebhookProvider(normalizedRouteContext);
+  return {
+    provider,
+    confidence: provider === "unknown" ? "likely" : "high"
+  };
 }
-function hasStripeWebhookSignatureVerification(content) {
-  return content.includes("stripe.webhooks.constructEvent") || content.includes("webhooks.constructEvent") || content.includes("constructEvent(");
+function getWebhookProvider(normalizedRouteContext) {
+  if (normalizedRouteContext.includes("stripe-signature") || normalizedRouteContext.includes("stripe_webhook_secret") || normalizedRouteContext.includes("stripe.webhooks") || normalizedRouteContext.includes("constructevent(") || normalizedRouteContext.includes("stripe") && normalizedRouteContext.includes("webhook")) {
+    return "stripe";
+  }
+  if (normalizedRouteContext.includes("resend") && normalizedRouteContext.includes("webhook")) {
+    return "resend";
+  }
+  if (normalizedRouteContext.includes("clerk_webhook_secret") || normalizedRouteContext.includes("clerk") && normalizedRouteContext.includes("webhook")) {
+    return "clerk";
+  }
+  if (normalizedRouteContext.includes("x-github-event") || normalizedRouteContext.includes("x-hub-signature")) {
+    return "github";
+  }
+  if (normalizedRouteContext.includes("x-shopify-hmac-sha256")) {
+    return "shopify";
+  }
+  return "unknown";
 }
-function isClerkWebhookRoute(relativeFile, content) {
-  const normalizedFile = relativeFile.toLowerCase();
+function hasWebhookSignatureVerification(content, provider) {
   const normalizedContent = content.toLowerCase();
-  return (normalizedContent.includes("clerk") || normalizedContent.includes("clerk_webhook_secret")) && (normalizedFile.includes("webhook") || normalizedContent.includes("webhook"));
+  if (provider === "stripe") {
+    return normalizedContent.includes("stripe.webhooks.constructevent") || normalizedContent.includes("webhooks.constructevent") || normalizedContent.includes("constructevent(");
+  }
+  if (provider === "clerk") {
+    return (normalizedContent.includes("new webhook(") || normalizedContent.includes("webhook(") || normalizedContent.includes("svix")) && (normalizedContent.includes(".verify(") || normalizedContent.includes("verify(") || normalizedContent.includes("verifywebhook"));
+  }
+  if (provider === "github") {
+    return (normalizedContent.includes("x-hub-signature") || normalizedContent.includes("x-hub-signature-256")) && hasHmacOrVerifyCall(normalizedContent);
+  }
+  if (provider === "shopify") {
+    return normalizedContent.includes("x-shopify-hmac-sha256") && hasHmacOrVerifyCall(normalizedContent);
+  }
+  if (provider === "resend") {
+    return normalizedContent.includes("verifywebhook") || (normalizedContent.includes("new webhook(") || normalizedContent.includes("webhook(") || normalizedContent.includes("svix")) && hasHmacOrVerifyCall(normalizedContent);
+  }
+  return normalizedContent.includes("constructevent(") || normalizedContent.includes("verifywebhook") || normalizedContent.includes("signature") && hasHmacOrVerifyCall(normalizedContent) || normalizedContent.includes("webhook") && normalizedContent.includes("verify(");
+}
+function hasHmacOrVerifyCall(normalizedContent) {
+  return normalizedContent.includes("verify(") || normalizedContent.includes(".verify(") || normalizedContent.includes("verifywebhook") || normalizedContent.includes("createhmac") || normalizedContent.includes("timingsafeequal") || normalizedContent.includes("subtle.verify");
+}
+function getWebhookSignatureSuggestion(provider) {
+  if (provider === "stripe") {
+    return "Use stripe.webhooks.constructEvent(...) with the Stripe signature header before handling the event.";
+  }
+  if (provider === "clerk") {
+    return "Verify the event with Svix before handling it.";
+  }
+  if (provider === "github") {
+    return "Verify the GitHub signature using the raw request body, X-Hub-Signature-256 header, and webhook secret.";
+  }
+  if (provider === "shopify") {
+    return "Verify the Shopify HMAC using the raw request body, X-Shopify-Hmac-Sha256 header, and webhook secret.";
+  }
+  if (provider === "resend") {
+    return "Verify the Resend webhook signature before handling the event.";
+  }
+  return "Verify the provider signature using the raw request body and signature header before trusting the event.";
+}
+function createApiAuthFixPrompt(file) {
+  return `Review the API route at ${file}.
+
+Goal:
+Determine whether this route should be public or protected.
+
+Instructions:
+- Inspect the existing authentication/session pattern used in this project.
+- If this route handles private data, user-specific data, uploads, writes, or admin actions, add the existing auth/session check.
+- Do not introduce a new auth provider.
+- Do not refactor unrelated code.
+- Keep the current behavior unchanged.
+- If this route is intentionally public, add a short comment explaining why.
+
+Return:
+- A short explanation of what you changed.
+- The updated code.
+- Any edge cases I should test.`;
 }
-function hasClerkWebhookSignatureVerification(content) {
-  return content.includes("new Webhook(") || content.includes(".verify(") || content.includes("svix");
+function createMissingEnvVariableFixPrompt(variableName, files) {
+  return `Update the environment documentation for this project.
+
+The variable ${variableName} is used in ${formatPromptFileList(files)} but is missing from .env.example.
+
+Instructions:
+- Add ${variableName}= to .env.example.
+- Do not add a real secret value.
+- Check if related environment variables used in the same file should also be documented.
+- Keep comments clear and safe for public repos.
+
+Return:
+- The updated .env.example lines.
+- A short explanation.`;
+}
+function createLargeFileFixPrompt(file) {
+  return `Review ${file}.
+
+Qodfy detected this as a large file.
+
+Goal:
+Suggest a safe refactor plan without changing behavior.
+
+Instructions:
+- Identify the main responsibilities inside the file.
+- Suggest smaller components, hooks, or utility files that can be extracted.
+- Do not rewrite the whole file at once.
+- Do not change UI behavior.
+- Do not change business logic.
+- Prioritize low-risk extractions first.
+
+Return:
+- A short responsibility breakdown.
+- A step-by-step refactor plan.
+- The safest first extraction.`;
+}
+function createAiRateLimitFixPrompt(file) {
+  return `Review the AI-related API route at ${file}.
+
+Goal:
+Add cost and abuse protection safely.
+
+Instructions:
+- Check the existing project patterns for auth, usage limits, or rate limiting.
+- If this route can be called by users, add rate limiting or per-user usage protection.
+- Do not introduce a new service unless necessary.
+- Do not change the AI provider or model behavior.
+- Keep the current response format unchanged.
+- If the route is intentionally public, explain why and recommend a safe limit.
+
+Return:
+- The safest protection approach.
+- The updated code.
+- Any environment variables required.`;
+}
+function createWebhookSignatureFixPrompt(file) {
+  return `Review the webhook API route at ${file}.
+
+Goal:
+Verify that webhook signature validation happens before the event is handled.
+
+Instructions:
+- Detect which provider this webhook belongs to based on imports, headers, and environment variables.
+- Use the provider's existing verification pattern if already present.
+- Do not process the webhook event before verification unless required by the provider.
+- Do not introduce unrelated changes.
+- If verification already exists, explain where it happens.
+
+Return:
+- Whether signature verification exists.
+- If missing, the safest code change.
+- Any test cases to run.`;
+}
+function createClientSideSecretFixPrompt(file, variableName) {
+  return `Review the client-side file at ${file}.
+
+Qodfy found ${variableName}, which does not start with NEXT_PUBLIC_.
+
+Goal:
+Confirm whether this environment variable may be exposed to the browser.
+
+Instructions:
+- Check whether this file is a client component or browser-executed code.
+- If ${variableName} is server-only, move access to a server component, API route, or server action.
+- Do not rename environment variables unless necessary.
+- Do not add real secret values.
+- Keep existing behavior unchanged.
+
+Return:
+- Whether the variable is safe in this file.
+- The safest code change if it is not safe.
+- Any edge cases I should test.`;
+}
+function createHardcodedSecretFixPrompt(file, secretLabel) {
+  return `Review ${file} for a possible hardcoded ${secretLabel}.
+
+Goal:
+Remove any real secret from source code without changing behavior.
+
+Instructions:
+- Do not print or copy the secret value in your response.
+- Move the value to an environment variable if it is a real secret.
+- Add only the variable name to .env.example.
+- Recommend rotating the secret if it may have been committed.
+- Do not refactor unrelated code.
+
+Return:
+- Whether this looks like a real secret.
+- The safest code change.
+- Any follow-up security steps.`;
+}
+function createMissingEnvExampleFixPrompt() {
+  return `Create or update .env.example for this project.
+
+Goal:
+Document the environment variables required to run and deploy the app.
+
+Instructions:
+- Inspect process.env usage in the project.
+- Add variable names only.
+- Do not add real secret values.
+- Use empty placeholders like VARIABLE_NAME=.
+- Add short comments only where they help future maintainers.
+
+Return:
+- The proposed .env.example content.
+- A short explanation of any variables that need manual confirmation.`;
+}
+function createProjectRootFixPrompt() {
+  return `Review how Qodfy is being run for this project.
+
+Goal:
+Make sure the scanner is pointed at the correct app root.
+
+Instructions:
+- Find the folder that contains the app package.json.
+- If this is a monorepo, identify the Next.js app folder.
+- Do not move files or refactor the project.
+- Recommend the correct qodfy scan --path command.
+
+Return:
+- The correct folder to scan.
+- The exact command to run.`;
+}
+function createPackageJsonFixPrompt() {
+  return `Review package.json.
+
+Goal:
+Make package.json readable so tooling can detect the project correctly.
+
+Instructions:
+- Check for invalid JSON syntax.
+- Keep existing dependencies and scripts unchanged unless they are malformed.
+- Do not upgrade dependencies.
+- Do not refactor unrelated files.
+
+Return:
+- The corrected package.json change.
+- A short explanation.`;
+}
+function createNextNotDetectedFixPrompt() {
+  return `Review this project structure.
+
+Goal:
+Determine whether Qodfy is scanning the correct Next.js app folder.
+
+Instructions:
+- Check whether this is a monorepo.
+- Find the package.json that includes next as a dependency.
+- Do not install or remove packages.
+- Recommend the correct qodfy scan --path command if needed.
+
+Return:
+- Whether this is a Next.js app.
+- The exact folder Qodfy should scan.`;
+}
+function createReadmeFixPrompt() {
+  return `Create a practical README for this project.
+
+Goal:
+Help developers run, configure, and maintain the app.
+
+Instructions:
+- Include setup commands, environment variable documentation, local development, build, and deployment notes.
+- Do not include real secret values.
+- Keep the README concise and accurate.
+- Do not invent features that are not in the project.
+
+Return:
+- The README content.
+- Any assumptions that need confirmation.`;
+}
+function formatPromptFileList(files) {
+  if (files.length === 1) {
+    return files[0];
+  }
+  return `${files.length} files: ${formatFileList(files)}`;
 }
 function isPackageJsonObject(data) {
   return typeof data === "object" && data !== null && !Array.isArray(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodfy/core",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Scanner engine for Qodfy, an open-source launch readiness scanner for AI-built apps.",
   "keywords": [
     "qodfy",