feat: add agent:prime script for agent-context indexing

[google-labs-jules]

Add the agent:prime script entry to package.json.
Add scripts/agent-prime.mjs to generate/update .agent-context.json gracefully.
Implement Vitest tests for the agent context indexing script.
Update vite.config.ts to include .test.ts files inside /tests.

---

PR created automatically by Jules for task 12915572335704980998 started by @arii

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[github-actions]

🚀 Deployment Details (Last updated: Jul 26, 2026, 10:54 AM PST)

🚀 Pushed to gh-pages; publish in progress

• Preview URL: https://arii.github.io/tech-dancer/add-agent-prime-script-12915572335704980998/
• Preview Dashboard: https://arii.github.io/tech-dancer/previews/index.html
• Commit SHA: 00185ef
• Marker File: verify here

[github-actions]

🐙 GitHub Models Code Review

Powered by GitHub Models

Reviewing: PR #3955

Model: gpt-4o-mini

Code Review Feedback

[ARCHITECTURE] Review

Upon reviewing the changes in the Pull Request, I have identified several issues that need to be addressed. Below are the findings based on the provided diff and context.

Findings

1. Blocking Issue: Lack of Tests for New Functionality

   • Snippet: The initial review indicated a lack of tests for the new functionality in scripts/agent-prime.mjs. While tests have been added in tests/unit/agent-prime.test.ts, it is crucial to ensure that all edge cases are covered adequately.
   • Status: Open
   • Confidence: High
   • Counterexample: The tests do cover various scenarios, but additional edge cases could be considered, such as handling of unexpected file structures or permissions issues.

2. Blocking Issue: Use of execSync Can Lead to Performance Issues

   • Snippet:

     gitSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();

   • Issue: The use of execSync blocks the event loop, which can lead to performance issues, especially in larger applications or when this script is called frequently.
   • Status: Open
   • Confidence: High
   • Counterexample: If this script is called in a high-frequency scenario, it could lead to performance bottlenecks. An asynchronous alternative should be considered.

3. Blocking Issue: Error Handling for JSON Parsing is Too Lenient

   • Snippet:

     const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));

   • Issue: The error handling for JSON parsing does not provide sufficient feedback to the user. If parsing fails, it should throw an error or log a more descriptive message.
   • Status: Open
   • Confidence: High
   • Counterexample: If package.json contains invalid JSON, the user will not be informed adequately about the nature of the error.

4. Blocking Issue: New Untrusted Input Path Introduced by Reading package.json Without Validation

   • Snippet:

     const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));

   • Issue: The script reads package.json without validating its contents, which could lead to security vulnerabilities if the file is tampered with.
   • Status: Open
   • Confidence: High
   • Counterexample: If an attacker modifies package.json to include malicious content, the script may behave unexpectedly.

5. Non-blocking Issue: Lack of User Feedback When Git SHA Retrieval Fails

   • Snippet:

     console.warn(`[agent:prime] Command failed: "git rev-parse HEAD". Using fallback "unknown". Error: ${error.message}`);

   • Issue: While there is some logging, it could be improved to provide clearer feedback to the user about what went wrong.
   • Status: Open
   • Confidence: Medium
   • Counterexample: Users may not notice the warning if they are not monitoring the console output closely.

Summary

The changes introduced in this PR have made significant progress, particularly with the addition of tests. However, there are still several critical issues that need to be addressed, particularly around performance, error handling, and security.

Final Verdict

Given the presence of multiple blocking issues that could affect the functionality and security of the application, I must conclude that this PR cannot be merged until these issues are resolved.

#### [PERFORMANCE] Review
Upon reviewing the provided pull request changes, I have identified the following issues based on the performance engineering perspective, focusing on expensive computations, redundant re-renders, large bundle impacts, and inefficient data structures.

### Findings

1. **Blocking Call with `execSync`**:
   - **Snippet**: 
     ```javascript
     gitSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
     ```
   - **Issue**: The use of `execSync` is a blocking call, which can lead to performance issues, especially if the command takes a long time to execute. This can stall the entire process until the command completes.
   - **Status**: open
   - **Confidence**: high
   - **Counterexample**: If the Git repository is large or the command is run in a slow environment, the script could hang indefinitely, causing a poor user experience.
   - **Fix Summary**: Consider using asynchronous alternatives such as `exec` from `child_process` or caching the result to avoid repeated calls.

2. **Error Handling for JSON Parsing**:
   - **Snippet**: 
     ```javascript
     const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
     ```
   - **Issue**: The error handling for JSON parsing is too lenient and lacks feedback. If the JSON is malformed, it will silently fall back to the default package name without informing the user adequately.
   - **Status**: open
   - **Confidence**: high
   - **Counterexample**: If `package.json` contains invalid JSON, the user will not be notified of the issue, leading to confusion about why the default name is used.
   - **Fix Summary**: Implement logging or throw an error to inform the user of the issue.

3. **Redundant Fallback for Git SHA Retrieval**:
   - **Snippet**: 
     ```javascript
     console.warn(`[agent:prime] Command failed: "git rev-parse HEAD". Using fallback "unknown". Error: ${error.message}`);
     ```
   - **Issue**: There is no logging to indicate that the Git SHA retrieval failed, which could be useful for debugging.
   - **Status**: open
   - **Confidence**: high
   - **Counterexample**: If the command fails, users will not know why the SHA is 'unknown', leading to potential confusion.
   - **Fix Summary**: Add logging to indicate that the Git SHA retrieval failed.

4. **Untrusted Input Path from `package.json`**:
   - **Snippet**: 
     ```javascript
     const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
     ```
   - **Issue**: Reading `package.json` without validation introduces a new untrusted input path. If an attacker can modify this file, they can manipulate the behavior of the script.
   - **Status**: open
   - **Confidence**: high
   - **Counterexample**: If `package.json` is tampered with to include malicious code, it could lead to security vulnerabilities.
   - **Fix Summary**: Implement validation checks on `pkgData` after parsing to ensure it meets expected criteria.

### Summary
The changes introduced in this pull request include a new script for generating agent context, which has several performance and security concerns that need to be addressed. The use of blocking calls, insufficient error handling, and lack of validation for untrusted input paths are critical issues that could affect the performance and security of the application.

Based on the findings, I recommend addressing the identified issues before merging this pull request.

```json

[SECURITY] Review

Upon reviewing the provided pull request, I have identified the following issues related to security, specifically concerning untrusted input paths and data validation:

1. Untrusted Input Path:

   • Line: 26
   • Snippet: const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
   • Issue: The code reads package.json without any validation checks after parsing. This introduces a new untrusted input path, as the contents of package.json can be manipulated, potentially leading to unexpected behavior or security vulnerabilities if the data is not properly validated.
   • Status: Open
   • Confidence: High
   • Counterexample: If an attacker modifies package.json to include malicious content, it could lead to unexpected behavior in the application.
   • Fix Summary: Implement validation checks on pkgData after parsing to ensure it meets expected criteria (e.g., checking that pkgData.name is a valid string).

2. Error Handling for JSON Parsing:

   • Line: 30
   • Snippet: const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
   • Issue: The error handling for JSON parsing is too lenient and lacks sufficient feedback. While there is a warning logged, it does not provide enough context for debugging or recovery.
   • Status: Open
   • Confidence: High
   • Counterexample: If package.json contains invalid JSON, the user will receive a generic warning without understanding what went wrong.
   • Fix Summary: Implement more robust error handling that logs detailed information about the parsing failure.

3. Lack of User Feedback on Fallback Behavior:

   • Line: 12
   • Snippet: gitSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
   • Issue: There is no logging to indicate that the Git SHA retrieval failed, which could lead to confusion for users running the script.
   • Status: Open
   • Confidence: High
   • Counterexample: If the command fails, the user will not be informed that the fallback value of "unknown" is being used.
   • Fix Summary: Add logging to indicate that the Git SHA retrieval failed and that a fallback value is being used.

Based on the findings above, I recommend addressing the identified issues to ensure the security and robustness of the new functionality introduced in this pull request.

[STYLE] Review

Upon reviewing the provided changes in the Pull Request, I have identified several issues that need to be addressed. Below are the findings based on the diff and the context provided.

Findings

1. Lack of Tests for New Functionality

   • File: tests/unit/agent-prime.test.ts
   • Line: 1
   • Snippet: import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
   • Issue: The tests for the new functionality in agent-prime.mjs are present, but the initial review indicated a lack of tests. This has been resolved with the addition of comprehensive tests.
   • Status: Resolved
   • Confidence: High
   • Counterexample: N/A
   • Fix Summary: Tests have been implemented for the generateAgentContext and primeAgentContext functions.

2. Use of execSync Can Lead to Performance Issues

   • File: scripts/agent-prime.mjs
   • Line: 12
   • Snippet: gitSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
   • Issue: The use of execSync is blocking and can lead to performance issues. It is recommended to use asynchronous alternatives.
   • Status: Open
   • Confidence: High
   • Counterexample: If the command takes a long time to execute, it will block the event loop, causing performance degradation.
   • Fix Summary: Consider refactoring to use exec with a callback or promises.

3. Error Handling for JSON Parsing is Too Lenient

   • File: scripts/agent-prime.mjs
   • Line: 26
   • Snippet: const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
   • Issue: The error handling for JSON parsing does not provide sufficient feedback to the user. It should log or throw an error to inform the user of the issue.
   • Status: Open
   • Confidence: High
   • Counterexample: If package.json is malformed, the user will not receive adequate feedback about the failure.
   • Fix Summary: Implement logging or throw an error to inform the user of the issue.

4. Redundant Fallback for Git SHA Retrieval Without User Feedback

   • File: scripts/agent-prime.mjs
   • Line: 12
   • Snippet: gitSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
   • Issue: There is no logging to indicate that the Git SHA retrieval failed, which can lead to confusion.
   • Status: Open
   • Confidence: High
   • Counterexample: If the command fails, the user will not know why the SHA is 'unknown'.
   • Fix Summary: Add logging to indicate that the Git SHA retrieval failed.

5. New Untrusted Input Path Introduced by Reading package.json Without Validation

   • File: scripts/agent-prime.mjs
   • Line: 27
   • Snippet: const pkgData = JSON.parse(readFileSync(pkgPath, 'utf8'));
   • Issue: The code reads package.json without validating its contents, which could lead to security issues.
   • Status: Open
   • Confidence: High
   • Counterexample: If an attacker modifies package.json, it could lead to unexpected behavior.
   • Fix Summary: Implement validation checks on pkgData after parsing to ensure it meets expected criteria.

Summary

The PR has resolved the issue of lacking tests, but several other issues remain open that need to be addressed to ensure the code's robustness and maintainability.

Final Verdict:

JSON Findings Block

---
*Generated by github-models-code-review*

[arii]

🤖 AI Technical Audit

ANTI-AI-SLOP

The implementation of scripts/agent-prime.mjs is clean and adheres to the single-responsibility principle. I have identified a minor redundancy in process.argv checks; using import.meta.url for the execution check is idiomatic, but the script can be further simplified by removing unnecessary error-catching blocks that just silence potential issues (like missing package.json). Keep the logic focused on the task at hand: generating the context.

FINAL RECOMMENDATION

Approved with Minor Changes

DEFINITION OF DONE

1. Consolidate the try/catch blocks in generateAgentContext to a single utility helper or remove the empty catch blocks if the default values are sufficient, as silent failure masks potential environment configuration issues.
2. Ensure the generated .agent-context.json is added to .gitignore if it is an artifact of the build process, preventing accidental commits of local state.
3. Verify tests, run audit for anti-patterns, and update snapshots if necessary.

Review automatically published via RepoAuditor.