fix(generator): make output permission error clear and user-friendly

[sahillllllllll-bit]

Description

• Improves error handling when the output directory is not writable.
• Replaces raw Node.js EACCES permission errors with a clear, user-friendly message.
• Guides users to choose a writable directory or fix permissions instead of showing a cryptic crash.

Related issue(s)
fixes #1842

Before

• Error is technical and not helpful for beginners.
• No guidance on how to fix the problem.

◇ Generation failed
Generator Error: EACCES: permission denied, mkdir '/root/output'

After

• Generator detects permission errors explicitly.
• Shows a clear, user-friendly message:

◇ Generation failed
Permission denied: Cannot write to the output directory.
Please choose a directory you have write access to, or adjust the permissions for the target directory.

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling and messaging when creating the output directory—permission or write-access problems now produce clear, user-friendly errors to help resolve access issues quickly.
  • Retained existing behavior for the "force write" option; verification of the target directory is preserved for non-forced writes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3bd71af

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[asyncapi-bot]

What reviewer looks at during PR review

The following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.

1. PR Title: Use a concise title that follows our Conventional Commits guidelines and clearly summarizes the change using imperative mood (it means spoken or written as if giving a command or instruction, like "add new helper for listing operations")

   Note - In Generator, prepend feat: or fix: in PR title only when PATCH/MINOR release must be triggered.

2. PR Description: Clearly explain the issue being solved, summarize the changes made, and mention the related issue.

   Note - In Generator, we use Maintainers Work board to track progress. Ensure the PR Description includes Resolves #<issue-number> or Fixes #<issue-number> this will automatically close the linked issue when the PR is merged and helps automate the maintainers workflow.

3. Documentation: Update the relevant Generator documentation to accurately reflect the changes introduced in the PR, ensuring users and contributors have up-to-date guidance.

4. Comments and JSDoc: Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions, so others can easily understand and use the code.

5. DRY Code: Ensure the code follows the Don't Repeat Yourself principle. Look out for duplicate logic that can be reused.

6. Test Coverage: Ensure the new code is well-tested with meaningful test cases that pass consistently and cover all relevant edge cases.

7. Commit History: Contributors should avoid force-pushing as much as possible. It makes it harder to track incremental changes and review the latest updates.

8. Template Design Principles Alignment: While reviewing template-related changes in the packages/ directory, ensure they align with the Assumptions and Principles. If any principle feels outdated or no longer applicable, start a discussion these principles are meant to evolve with the project.

9. Reduce Scope When Needed: If an issue or PR feels too large or complex, consider splitting it and creating follow-up issues. Smaller, focused PRs are easier to review and merge.

10. Bot Comments: As reviewers, check that contributors have appropriately addressed comments or suggestions made by automated bots. If there are bot comments the reviewer disagrees with, react to them or mark them as resolved, so the review history remains clear and accurate.

[coderabbitai]

📝 Walkthrough

Walkthrough

Wraps directory creation in the generator with a try/catch to intercept filesystem permission errors (EACCES) and throw a user-friendly permission-denied error; other errors are rethrown. Subsequent directory validation is moved outside the try/catch, preserving forceWrite behavior.

Changes

Cohort / File(s)	Summary
Permission error handling apps/generator/lib/generator.js	Added a try/catch around directory creation to catch EACCES and throw a user-friendly permission error; rethrows other errors. Moved post-creation validation logic outside the try/catch so permission handling is separated from validation and forceWrite behavior remains unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly describes the main change (improving permission error messaging for clarity and user-friendliness), follows Conventional Commits format with 'fix:' prefix, uses imperative mood appropriately, and directly aligns with the changeset that wraps directory creation with try/catch for user-friendly permission error handling.
Linked Issues check	✅ Passed	The code changes successfully address issue #1842 by wrapping directory creation in try/catch to detect EACCES permission errors and replace them with user-friendly messages, matching the issue's requirement for clear permission denial messaging with actionable remediation guidance.
Out of Scope Changes check	✅ Passed	All changes in apps/generator/lib/generator.js are directly scoped to handling permission errors for the output directory, with no unrelated modifications present outside the permission error handling objectives defined in issue #1842.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@apps/generator/lib/generator.js`:
- Around line 248-260: In setupFSOutput(), the catch currently only treats
err.code === 'EACCES' as a friendly permission error; update the conditional to
also handle 'EPERM' and 'EROFS' so permission and read-only filesystem errors
are presented with the same user-friendly message for this.targetDir—i.e., check
if err.code is one of ['EACCES','EPERM','EROFS'] and throw the same descriptive
Error, otherwise rethrow the original err.

🧹 Nitpick comments (1)

apps/generator/lib/generator.js (1)

248-266: Add a regression test and align the JSDoc for the new error path.

Since this change improves user-facing messaging, a focused test that mocks fs.extra.mkdirpSync to throw EACCES (and asserts the new message) will guard against regressions. Also update the JSDoc above setupFSOutput() to mention permission-denied errors in its @throws description.

Based on learnings, ensure any new tests are placed under apps/generator/test/ and follow existing patterns.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/generator/lib/generator.js (1)

237-247: Update setupFSOutput JSDoc to mention permission-denied errors.

The @throws description only mentions verification failures, but the method now also throws when permissions prevent writing. Please update the doc to reflect that new error path.

📝 Suggested doc update

- * `@throws` {Error} If verification of the target directory fails and forceWrite is not enabled.
+ * `@throws` {Error} If the output directory is not writable (EACCES/EPERM/EROFS), or if verification fails when forceWrite is not enabled.

As per coding guidelines, ensure error conditions are documented.

🧹 Nitpick comments (2)

apps/generator/lib/generator.js (2)

248-260: Consider verifying write access for existing output directories.

If xfs.mkdirpSync behaves like standard mkdirp and doesn’t throw for an existing-but-non‑writable directory, the friendly message won’t trigger and later writes can still surface raw permission errors. Adding an explicit write-access check in the same try/catch would cover that case.

🔧 Suggested update

 try {
   xfs.mkdirpSync(this.targetDir);
+  fs.accessSync(this.targetDir, fs.constants.W_OK);
 } catch (err) {
   if (['EACCES', 'EPERM', 'EROFS'].includes(err.code)) {
     throw new Error(
       `Permission denied: cannot write to output directory "${this.targetDir}". ` +
       `Please choose a directory you have write access to, or adjust the permissions for the target directory.`
     );
   }
   throw err;
 }

---

254-257: Consider updating user-facing documentation to match the new error copy.

Since the CLI message changed, it may be worth updating Generator/CLI docs so users see consistent guidance.

Based on learnings, align docs with user-facing changes.