feat(gemini): Scans directories for old, forgotten files (temporal echoes) and suggests purification actions.

[polsala]

Implementation Summary

• Utility: nightly-temporal-echo-purifier
• Provider: gemini
• Location: node-utils/nightly-nightly-temporal-echo-purifi
• Files Created: 4
• Description: Scans directories for old, forgotten files (temporal echoes) and suggests purification actions.

Rationale

• Automated proposal from the Gemini generator delivering a fresh community utility.
• This utility was generated using the gemini AI provider.

Why safe to merge

• Utility is isolated to node-utils/nightly-nightly-temporal-echo-purifi.
• README + tests ship together (see folder contents).
• No secrets or credentials touched.
• All changes are additive and self-contained.

Test Plan

• Follow the instructions in the generated README at node-utils/nightly-nightly-temporal-echo-purifi/README.md
• Run tests located in node-utils/nightly-nightly-temporal-echo-purifi/tests/

Links

• Generated docs and examples committed alongside this change.

Mock Justification

• Not applicable; generator did not introduce new mocks.

[polsala]

🤖 Review by GROQ Agent

✅ What's solid

• Clear purpose & scope – the utility is self‑contained, does not touch any external services, and lives under its own folder, making it easy to reason about and to remove if needed.
• User‑friendly CLI – the --path and --age flags are documented in the README and the script prints a nicely formatted, whimsical report.
• Non‑destructive default – the tool never mutates the filesystem; it only reports, which is a safe baseline for a first‑release utility.
• Test coverage of core logic – the unit tests exercise the main helper functions (scanDirectoryForEchoes, reportEchoes, argument validation) and cover error paths such as missing directories and permission errors.
• Package metadata – package.json includes a test script, a proper main entry, and a MIT license, so the utility can be installed and run independently.

🧪 Tests

Area	Feedback
Mocking strategy	The tests replace fs methods with Jest mocks, which isolates the logic nicely. However, the mock setup is repeated in several beforeEach blocks. Consider extracting a helper like mockFs({ files, stats }) to keep the test file DRY.
Date handling	The suite overwrites global.Date with a Jest mock (global.Date = jest.fn(() => now)). This approach also replaces Date.now, new Date().getTime(), etc., and can break other modules that rely on the native constructor. A safer pattern is to use jest.useFakeTimers('modern') and jest.setSystemTime(now). Example: js\njest.useFakeTimers('modern');\njest.setSystemTime(new Date('2023-01-01T12:00:00Z'));\n
Restoring globals	The afterAll block attempts to restore global.Date with RealDate, but RealDate is never defined, leaving the global in a mocked state for any subsequent tests. Define it at the top of the file: js\nconst RealDate = Date;\n
Missing main import	The test suite calls main() directly, but the source file does not export a main function. Either export it (module.exports = { main, ... }) or invoke the script via require('../src/index') and call the exported entry point.
Recursive scanning	Current tests only verify a flat directory. If recursion is a future feature, add a test that includes a nested folder and asserts that files inside are (or are not) reported, depending on the intended behavior.
Edge‑case validation	Add a test for non‑numeric --age values that are numeric strings (e.g., "30"). The current parser treats them as strings; ensure Number(age) conversion and validation are exercised.
Coverage gaps	The parseArgs helper is not directly unit‑tested. A small test suite for it would guarantee that missing values, boolean flags, and duplicate flags behave as expected.

🔒 Security

• Path validation – The script trusts the user‑provided --path argument and passes it straight to fs.readdirSync. While this is fine for a local CLI, consider adding a sanity check that the path is absolute or resolves within a known base directory to avoid accidental scans of system‑wide locations. Example:
  js\nconst resolved = path.resolve(args.path);\nif (!resolved.startsWith(process.cwd())) {\n console.error('Refusing to scan outside the project directory');\n process.exit(1);\n}\n |
• Symlink handling – fs.lstatSync is used only for the top‑level check. When iterating over files, fs.statSync follows symlinks, which could lead to scanning outside the intended tree (e.g., a symlink to /etc). Switching to fs.lstatSync for each entry and optionally ignoring symlinks would tighten the boundary. |
• Error messages – The utility prints raw error messages (error.message) to stderr. This is acceptable for a developer tool, but be aware that in a production environment you might want to avoid leaking filesystem paths. Consider sanitising or prefixing messages with a generic tag. |
• Dependency surface – The only runtime dependency is Node’s built‑in fs and path. The dev dependency on jest is fine. No external network calls or native modules are introduced, keeping the attack surface minimal.

🧩 Docs / Developer Experience

• README consistency – The folder name in the repository is nightly-nightly-temporal-echo-purifi (missing the trailing “er”), while the README and usage examples refer to nightly-temporal-echo-purifier. Align the naming to avoid confusion (nightly-temporal-echo-purifier). |
• Installation instructions – The README tells users to clone the entire ApocalypsAI repo and then cd into the utility folder. Since the utility is a standalone npm package, you could also publish it (or at least allow npm install from the subdirectory) and provide a one‑liner:
  bash\nnpm install ./node-utils/nightly-temporal-echo-purifier\n |
• CLI help output – The script currently prints a custom “Usage:” message only when arguments are missing. Adding a --help flag that prints the same usage information would improve discoverability. |
• Exit codes – The code calls process.exit(1) on argument errors but never on success. Document the exit codes in the README (0 = success, 1 = usage error, other non‑zero = runtime error). |
• Node version – The README mentions “Node.js v14 or higher”, but the package.json does not enforce an engine range. Adding "engines": { "node": ">=14" } helps users and CI enforce compatibility. |
• Example output – Include a short snippet of the console output (both the “no echoes” and “found echoes” cases) in the README so users know what to expect. |

🧱 Mocks / Fakes

• Centralised mock file – Rather than mocking fs in each test, create a __mocks__/fs.js file that exports the mocked methods and tracks calls. Jest will automatically use it when you jest.mock('fs'). This makes the intent clearer and reduces boilerplate. |
• Avoid over‑mocking – The current tests mock all fs methods, which means the implementation cannot be exercised against a real filesystem. Adding an integration test that creates a temporary directory with real files (using fs.mkdtempSync or the tmp package) would give confidence that the path handling and statSync logic work with actual OS metadata. |
• Console mocking – The suite replaces console.log and console.error with Jest spies. That’s fine, but remember to restore them after each test (mockRestore) to avoid cross‑test contamination. |
• Reusable test data – The repeated testDirPath and maxAge constants could be defined once at the top of the file and reused, making the test file easier to maintain. |

---

Quick win checklist

• Export main (or rename the entry point) so tests can import it cleanly.
• Fix the global.Date restoration (const RealDate = Date;).
• Switch to jest.useFakeTimers('modern') for deterministic date handling.
• Add a --help flag and document exit codes.
• Align folder and utility naming across the repo and README.
• Consider recursive scanning or explicitly document that only top‑level files are examined.
• Harden path handling against symlinks and out‑of‑scope directories.

These adjustments will tighten the implementation, improve test reliability, and give end‑users a smoother experience while preserving the whimsical charm of the “Temporal Echo Purifier”.