Docs/add hooks reference

[AadithyaAle]

Summary

Adds the existing hooks reference documentation to the navigation structure. By updating the sidebar configuration, this ensures developers can easily discover and read the technical specifications for hooks on the documentation site.

Details

Modified docs/sidebar.json to expand the "Hooks" entry under the "Features" section. It now uses a nested menu containing "Overview" (docs/hooks) and "Reference" (docs/hooks/reference), which properly connects the previously unlinked docs/hooks/reference.md file into the site's structural hierarchy.

Related Issues

Fixes #20921

How to Validate

1. Review the changes in docs/sidebar.json to ensure the JSON syntax is valid.
2. Confirm that the new slug (docs/hooks/reference) correctly corresponds to the existing docs/hooks/reference.md file.
3. (If testing locally) Start the local docs preview to verify the "Hooks" tab now expands to show both "Overview" and "Reference".

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily enhances the documentation site's navigation by integrating the previously unlinked hooks reference into a more structured sidebar menu, thereby improving its discoverability and accessibility for developers. Additionally, a minor but important improvement was made to the execStreaming utility, refining how large error outputs are handled to ensure critical information is retained.

Highlights

• Documentation Navigation Enhancement: The docs/sidebar.json file was updated to transform the "Hooks" entry into a collapsible menu. This new structure now includes both an "Overview" and a "Reference" link, making the existing hooks reference documentation discoverable within the site's navigation.
• Improved Error Truncation: The packages/core/src/utils/shell-utils.ts file was modified to change how large stderr outputs are truncated. Instead of truncating the end, the new logic truncates the beginning of the message, ensuring the most recent error information is preserved. Newlines were also added for better readability of the truncation message.

Changelog

• docs/sidebar.json
  • Converted the "Hooks" entry from a direct link to a nested menu.
  • Added "Overview" and "Reference" sub-items under the "Hooks" menu.
  • Set the "Hooks" menu to be collapsed by default.
• packages/core/src/utils/shell-utils.ts
  • Modified the execStreaming function's error handling for stderr.
  • Changed the truncation strategy for large stderr messages to keep the tail instead of the head.
  • Introduced newlines around the truncation message for improved readability.

Activity

• The author has updated relevant documentation and the README.
• The changes have been validated on Linux using npm run.
• The pull request addresses and fixes issue Docs: add hooks reference file to structure #20921.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request updates the documentation sidebar to include a reference page for hooks, which aligns with the PR's description.

However, it also includes an unrelated change to packages/core/src/utils/shell-utils.ts. While the intent to improve stderr truncation is good, the implementation introduces a critical issue where multi-byte Unicode characters can be corrupted. It also doesn't fully achieve the stated goal of keeping the tail of the error log due to how stderr is collected. I've provided a review comment with a code suggestion to fix the character corruption issue.

Per the repository's contribution guidelines, it's best to keep pull requests focused on a single concern. The change to shell-utils.ts should ideally be in a separate PR.

[gemini-code-assist]

This new implementation for truncating stderr has a couple of issues:

1. Unicode Corruption: Using string.slice() to truncate can corrupt multi-byte Unicode characters, as it operates on UTF-16 code units, not bytes. This violates a general rule for this repository. It's safer to slice the Buffer before converting it to a string.

2. Incorrect Truncation Logic: The comment // If it's too large, keep the TAIL instead of the HEAD is misleading. The current stderr collection logic (lines 803-808) saves the head of the error stream. This change then takes the tail of that collected head. For a very large error output, this means the most important final error messages will be lost entirely. The collection logic should be changed to capture the tail of the stream if that is the goal.

Here is a suggestion to fix the Unicode corruption issue and improve efficiency by avoiding the creation of a potentially huge intermediate string:

            const stderrBuffer = Buffer.concat(errorChunks);
            let stderr: string;

            // If it's too large, keep the TAIL instead of the HEAD
            if (stderrTotalBytes >= MAX_STDERR_BYTES) {
              stderr =
                '\n...[truncated]\n' +
                stderrBuffer.slice(-MAX_STDERR_BYTES).toString('utf8');
            } else {
              stderr = stderrBuffer.toString('utf8');
            }

References

1. When truncating strings that may contain multi-byte Unicode characters (e.g., emojis), use methods that operate on grapheme clusters (like Intl.Segmenter or Array.from()) instead of UTF-16 code units (string.length, string.slice()) to prevent character splitting.

[AadithyaAle]

"Thanks for catching that, @gemini-code-assist! An unrelated local commit accidentally got bundled into this branch when I created it.

I have reverted the changes to shell-utils.ts so this PR is strictly focused on adding the hooks reference to the documentation structure, per the repository's single-concern guidelines. I'll open a separate PR for the shell-utils fix!"

[gemini-code-assist]

Thank you for addressing that, @AadithyaAle. Reverting the shell-utils.ts changes to ensure this pull request adheres to the single-concern guideline is a great step. I will now proceed with reviewing the documentation changes in docs/sidebar.json.

[g-samroberts]

Thank you for this PR, @AadithyaAle!

[AadithyaAle]

@g-samroberts Happy to help