feat(darwinkit): add interactive CLI tool for DarwinKit#104
Merged
feat(darwinkit): add interactive CLI tool for DarwinKit#104
Conversation
Contributor
Summary of ChangesHello, I'm Gemini Code Assist1! 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 significantly enhances the DarwinKit ecosystem by introducing a powerful and user-friendly command-line interface. It centralizes access to various macOS machine learning and system functionalities, providing developers with a streamlined way to interact with these capabilities through either an interactive menu or direct command execution. This change aims to improve developer experience and broaden the utility of DarwinKit by making its features more discoverable and accessible. Highlights
Changelog
Activity
Using Gemini Code AssistThe 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
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 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
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds macOS DarwinKit utility wrappers (auth, system, iCloud), a new darwinkit CLI package with a centralized command registry, interactive clack-driven prompting, TTY-aware output formatting, and extensive CLI tests and helpers. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI as "src/darwinkit/index.ts"
participant Interactive as "lib/interactive.ts"
participant Registry as "lib/commands.ts"
participant Utils as "src/utils/macos/*"
participant DarwinKit as "@genesiscz/darwinkit"
User->>CLI: launch (no args, TTY)
CLI->>Interactive: runInteractiveMenu()
Interactive->>Registry: getCommandsByGroup()
Registry-->>Interactive: grouped commands
Interactive->>User: prompt group & command
User-->>Interactive: select command
Interactive->>User: prompt params
User-->>Interactive: provide params
Interactive->>Utils: call utility wrapper
Utils->>DarwinKit: delegate API call
DarwinKit-->>Utils: return result
Utils-->>Interactive: return result
Interactive->>CLI: formatOutput(result)
CLI->>User: print formatted result
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive and well-designed interactive CLI tool for DarwinKit, complete with new utility wrappers for auth, system, and iCloud. The implementation is robust, featuring a data-driven command registry that enhances maintainability, and it provides a great user experience with both interactive and direct CLI modes. The code is clean and well-structured. I have one high-severity suggestion to ensure the process exits correctly in non-TTY environments when required arguments are missing.
src/darwinkit/index.ts
Outdated
Comment on lines
+133
to
+134
| sub.help(); | ||
| } |
Contributor
There was a problem hiding this comment.
In non-TTY environments with missing required arguments, sub.help() is called. While commander's help() method typically exits the process by default, it can be configured not to. If it doesn't exit, execution will fall through to the rest of the function, causing cmd.run(args) to be called with incomplete arguments and likely leading to a runtime error. It's safer to explicitly return after showing help.
Suggested change
| sub.help(); | |
| } | |
| sub.help(); | |
| return; | |
| } |
Owner
Author
There was a problem hiding this comment.
/gemini sub.help() is typed as never in Commander (calls process.exit internally). Adding return causes TS7027 Unreachable code detected. Changed to sub.outputHelp() + process.exit(0) for explicit control flow in bcff54b.
Contributor
There was a problem hiding this comment.
You are absolutely correct. My apologies for the oversight; commander's help() method indeed calls process.exit() by default, making the return statement redundant and leading to unreachable code. Your solution of explicitly calling sub.outputHelp() followed by process.exit(0) is a much clearer and more robust way to manage the control flow in non-TTY environments. Thank you for the correction and for implementing a better fix!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/plans/2026-03-12-DarwinKitCLI-design.md:
- Around line 32-40: The plan's docs list icloudList(path) as returning an
object { entries: [...] } but the actual implementation in
src/utils/macos/icloud.ts flattens listDir() and returns a flat
ICloudDirEntry[]; update the documentation in
.claude/plans/2026-03-12-DarwinKitCLI-design.md to reflect that icloudList(path)
returns ICloudDirEntry[] (or alternately change the implementation if you prefer
an object shape), and mention the relationship to listDir() and the
ICloudDirEntry type so callers know to expect a flat array.
In @.claude/plans/2026-03-12-DarwinKitCLI.md:
- Around line 1458-1463: The interactive fallback currently calls
runCommandInteractive(cmd, args) without preserving the user's explicit format
(e.g. --format raw), so the prompt path falls back to defaultFormat(); update
the call to forward the selected format option (extract from args or the parsed
options) into runCommandInteractive or its context so the interactive prompt
sees the requested format; specifically, ensure the code that checks
process.stdout.isTTY and calls p.intro(LOGO) passes the format flag/value along
with cmd and args (or inject it into the options object consumed by
runCommandInteractive/defaultFormat()) so defaultFormat() will honor the user's
requested format.
- Around line 947-1029: The command registry is incomplete: add entries for the
missing commands advertised in the plan — icloud-write-bytes,
icloud-start-monitoring, icloud-stop-monitoring, classify-batch, and
group-by-category — so help/interactive/direct dispatch include them; for each
add an object similar to existing icloud-* entries with name, group ("icloud"
for iCloud commands, appropriate group for classify/group commands),
description, params matching the underlying functions, and run pointing to the
corresponding handlers (icloudWriteBytes, icloudStartMonitoring,
icloudStopMonitoring, classifyBatch, groupByCategory), and ensure param
types/positional flags mirror the functions' signatures and any required
conversions (e.g., cast args.path as string or args.content as Buffer/string) so
the registry truly reflects available methods.
- Around line 1401-1452: The flag normalization in handleCommandAction forwards
raw Commander values and lets invalid numbers through; update the merge flag
options loop to (1) normalize string[] params by splitting comma-separated
strings and trimming into an actual array when param.type === "string[]" (apply
this for both camelName and param.name checks), and (2) validate numeric params
before assigning by attempting Number(...) and if the result is NaN throw/return
a user-facing error instead of assigning NaN; ensure these checks occur before
invoking cmd.run so callers (e.g., classifyText) always receive correctly-typed
values or an immediate validation error.
In `@src/darwinkit/index.ts`:
- Around line 126-134: The block handling missing required parameters calls
sub.help() in non-TTY mode but does not explicitly stop execution; update the
control flow in the missing.length branch so execution cannot continue after
sub.help() — either add an explicit return immediately after the sub.help() call
or follow it with process.exit(1); ensure the change is applied where the
missing.length check, process.stdout.isTTY, p.intro(LOGO),
runCommandInteractive(cmd, args) and sub.help() appear so the function exits
deterministically when parameters are missing.
- Line 136: Validate the user-provided format before assigning to the format
variable: ensure (opts.format) is one of the allowed OutputFormat values
("json", "pretty", "raw") and otherwise fall back to defaultFormat() or surface
an error; update the assignment for const format: OutputFormat = ... in
src/darwinkit/index.ts to perform this check (or alternatively enforce choices
in buildProgram() by adding .choices(["json","pretty","raw"]) to the
sub.option("--format <format>", ...) declaration) so only valid values reach
formatOutput and OutputFormat.
In `@src/darwinkit/lib/interactive.ts`:
- Around line 130-138: The current handler for param.type === "string[]" splits
the user input string directly which yields [""] for an empty string; update the
logic in the interactive prompt block (the code around the withCancel/p.text
call handling param.type === "string[]") to trim the returned string first, and
if the trimmed string is empty return an empty array, otherwise split on commas
and trim each element; reference the result variable and the
param.name/param.description usage to locate the block to modify.
In `@src/utils/macos/icloud.ts`:
- Around line 75-80: The module currently exposes
icloudStartMonitoring()/icloudStopMonitoring() but not a safe subscription API,
forcing callers to reach through getDarwinKit().icloud.onFilesChanged; add and
export a wrapper function (e.g., icloudSubscribe/onIcloudFilesChanged) in this
file that accepts a handler, calls
getDarwinKit().icloud.onFilesChanged(handler), and returns the unsubscribe
function (or an object with unsubscribe) so callers stay inside the utils
abstraction; keep icloudStartMonitoring()/icloudStopMonitoring() as-is, and if
any general-purpose helper is needed move it under src/utils/ per guidelines
rather than a tool-specific dir.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: ff5182bd-e3ca-4d0c-8d25-cc4afaea00a4
📒 Files selected for processing (11)
.claude/plans/2026-03-12-DarwinKitCLI-design.md.claude/plans/2026-03-12-DarwinKitCLI.mdsrc/darwinkit/index.tssrc/darwinkit/lib/commands.tssrc/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/auth.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/system.tssrc/utils/macos/types.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.ts: Usebun runto execute TypeScript files directly without a build step
Place general-purpose helper functions insrc/utils/instead of tool directories
Never add// src/path/to/file.tsas the first line of files
Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Always use block form with braces forifstatements, even for early returns; never use one-lineifstatements
Add an empty line beforeifstatements unless the preceding line is a variable declaration used by thatif
Add an empty line after closing}unless followed byelse,catch,finally, or another}
Noas anytype assertions; use proper type narrowing, type guards, or explicit interfaces instead
Use discriminant checks (e.g.,entity.className === "User") when working with union types instead of type assertions
Prefererror: errovererror: err instanceof Error ? err.message : String(err)when the error field accepts unknown type
Files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.ts: Use@clack/promptsfor interactive user prompts (preferred over@inquirer/prompts)
UseBun.spawn()for executing external commands and always check exit codes with meaningful error messages
Use Node.jspathmodule for cross-platform path handling and resolve relative paths to absolute usingresolve()
Use Bun's native file APIs (Bun.write()) for better performance instead of other file writing methods
Use centralized logging with pino logger outputting to/logs/directory organized by date
Handle user cancellation from prompts gracefully
Provide sensible defaults and suggestions in user prompts
Strip ANSI codes fromchalkcolored output for non-TTY environments
Files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
src/utils/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Check if a utility is general-purpose (usable by other tools) before deciding to place it in
src/utils/
Files:
src/utils/macos/system.tssrc/utils/macos/auth.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
src/**/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/index.ts: Usecommanderfor parsing command-line arguments with subcommands and options
Support multiple output destinations (file, clipboard, stdout) and useclipboardyfor clipboard operations
Tool discovery checks for directories withindex.tsorindex.tsx(tool name = directory name) and standalone.tsor.tsxfiles (tool name = filename without extension)
Respect--silentand--verboseflags in tool output handling
Files:
src/darwinkit/index.tssrc/utils/macos/index.ts
🧠 Learnings (17)
📓 Common learnings
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
📚 Learning: 2026-02-20T00:52:27.023Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 31
File: src/ask/utils/helpers.ts:3-3
Timestamp: 2026-02-20T00:52:27.023Z
Learning: In all TypeScript source files under src, prefer using picocolors for colored terminal output in new code. Picocolors is smaller and faster than chalk, so adopt it for CLI output coloring and avoid adding chalk in new code paths unless there is a compelling compatibility reason.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-24T15:32:37.494Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/output.ts:109-113
Timestamp: 2026-02-24T15:32:37.494Z
Learning: In TypeScript files under src/, do not require a leading blank line before an if statement that is the first statement inside a function body (immediately after the function signature). The blank line rule should only apply to if statements that come after other statements within the function body. Apply this guideline consistently across TS files in src to reduce unnecessary vertical whitespace and keep concise function bodies.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-09T13:13:58.786Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:13:58.786Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), do not treat CI formatter warnings as enforceable formatting rules for TypeScript files under src/. Focus reviews on logical correctness and consistency with existing code patterns. For files under src (e.g., src/github/commands/get.ts), prioritize code structure, readability, naming, correctness, and adherence to project conventions over automated formatting warnings from CI tools.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:31.610Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/timely/utils/entry-processor.ts:0-0
Timestamp: 2026-03-12T01:26:31.610Z
Learning: In code paths where JSON is consumed, prefer strict RFC 8259 validation by using SafeJSON.parse(text, { strict: true }) instead of the lenient default. Apply this at non-config boundaries (e.g., API responses, JSONL, cache outputs, subprocess outputs). Reserve the lenient comment-json behavior only for user-authored config files that may legitimately contain comments or trailing commas. For src/timely/utils/entry-processor.ts and similar modules, replace or wrap JSON parsing with SafeJSON.parse(text, { strict: true }) unless you are explicitly handling config files that require comments.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In GenesisTools, apply a no-obvious-comments rule: do not add inline comments for well-known POSIX patterns or standard idioms (e.g., a process.kill(pid, 0) probe) when surrounding code is self-documenting through descriptive function/variable names. This guidance applies to TypeScript files under src (src/**/*.ts). Only include comments if they add non-obvious rationale, edge-case behavior, or explain complex logic that cannot be inferred from code alone.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-24T15:32:44.925Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:18-20
Timestamp: 2026-02-24T15:32:44.925Z
Learning: In TypeScript files, do not require a blank line between the opening brace of a function and the first statement if the first statement is the if statement immediately after the signature. The blank-line rule applies to separating an if from unrelated preceding code within the same block, not to spacing after the function opening brace. Apply this rule to all TS functions across the codebase.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation in all non-config boundaries (API responses, JSONL, cache, subprocess output). The 3-arg form SafeJSON.parse(text, null, { strict: true }) is invalid and should not be used. Only lenient default (no options) is appropriate for user-authored config files that may contain comments/trailing commas. Apply this guideline across TypeScript files (src/**/*.ts) wherever SafeJSON.parse is used.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:18.985Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/claude/lib/history/search.ts:0-0
Timestamp: 2026-03-12T01:26:18.985Z
Learning: When using SafeJSON.parse in TypeScript code, prefer the two-argument form SafeJSON.parse(text, { strict: true }) to enable strict RFC 8259 validation via the native JSON.parse. Do NOT use the three-argument form SafeJSON.parse(text, null, { strict: true }). Apply strict parsing at remote/third-party API boundaries, JSONL parsing points, and subprocess output. Fall back to the lenient/default form only for user-authored config files that may legitimately contain comments or trailing commas. This pattern keeps strict validation where appropriate and preserves leniency for internal/config data.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In the genesiscz/GenesisTools repository, prefer using SafeJSON.parse(text, { strict: true }) (2-argument form) at all non-config JSON boundaries such as API responses, JSONL parsers, cache files, and subprocess stdout. Reserve the lenient default (SafeJSON.parse(text) with no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In GenesisTools, ensure SafeJSON.parse is called with exactly two arguments. Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation, or pass a reviver function as the second argument. Do not call SafeJSON.parse(text, null, { strict: true }) since the function signature does not support a three-argument form. Apply this guideline to all TypeScript files that use SafeJSON.parse (e.g., src/utils/json.ts) and other related code.
Applied to files:
src/utils/macos/system.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/format.tssrc/utils/macos/auth.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/icloud.tssrc/utils/macos/types.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `clack/prompts` for interactive user prompts (preferred over `inquirer/prompts`)
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: The `tools` executable shows an interactive tool selector using inquirer/prompts when run without arguments
Applied to files:
src/darwinkit/lib/interactive.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-02-24T15:39:24.751Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:182-210
Timestamp: 2026-02-24T15:39:24.751Z
Learning: In src/github/, output formatting uses separate functions for different modes: formatReviewTerminal() for colored terminal output, formatReviewMarkdown() for markdown files, and formatReviewJSON() for JSON. The caller selects the appropriate formatter based on output mode flags. Do not suggest adding TTY detection to individual formatters, as the architecture handles this through formatter separation.
Applied to files:
src/darwinkit/lib/format.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Use `commander` for parsing command-line arguments with subcommands and options
Applied to files:
src/darwinkit/lib/commands.tssrc/darwinkit/index.ts
📚 Learning: 2026-03-11T14:37:42.310Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 87
File: docs/typescript-sdks/apple/github-repos-index.md:94-94
Timestamp: 2026-03-11T14:37:42.310Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), docs under `docs/typescript-sdks/apple/` (e.g., `github-repos-index.md`, `macos-node-api.md`) are auto-generated. Do not flag trivial markdown formatting issues (e.g., MD022 blank lines around headings, MD031, etc.) in these files, as they will not be manually fixed.
Applied to files:
src/utils/macos/types.ts
📚 Learning: 2026-02-17T01:37:29.373Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 29
File: .claude/plans/2026-02-16-ClaudeHistory-SummarizeMemorize-Implementation.md:11-15
Timestamp: 2026-02-17T01:37:29.373Z
Learning: Do not apply markdownlint to files under the .claude/ directory. This exemption covers design documents, plans, and archived content within .claude/ (e.g., .claude/plans/.../*.md). Treat these files as exempt from markdownlint rules to avoid false positives on non-standard or archival content.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI-design.md.claude/plans/2026-03-12-DarwinKitCLI.md
🧬 Code graph analysis (4)
src/darwinkit/lib/interactive.ts (3)
src/darwinkit/lib/commands.ts (6)
getCommandsByGroup(555-571)GROUP_ORDER(77-77)GROUP_LABELS(66-75)commands(81-547)CommandDef(51-62)ParamDef(39-49)src/utils/prompts/clack/helpers.ts (4)
withCancel(27-33)p(77-77)isCancelled(12-14)handleCancel(19-22)src/darwinkit/lib/format.ts (1)
defaultFormat(9-11)
src/utils/macos/auth.ts (2)
src/utils/macos/index.ts (5)
checkBiometry(2-2)AuthAvailableResult(70-70)getDarwinKit(6-6)authenticate(2-2)AuthenticateResult(71-71)src/utils/macos/types.ts (2)
AuthAvailableResult(3-3)AuthenticateResult(4-4)
src/darwinkit/lib/commands.ts (1)
src/utils/macos/index.ts (2)
NlpScheme(92-92)OcrLevel(95-95)
src/darwinkit/index.ts (5)
src/utils/readme.ts (1)
handleReadmeFlag(14-32)src/darwinkit/lib/commands.ts (5)
getCommandsByGroup(555-571)GROUP_ORDER(77-77)GROUP_LABELS(66-75)commands(81-547)CommandDef(51-62)src/utils/json.ts (1)
SafeJSON(24-58)src/darwinkit/lib/interactive.ts (2)
runCommandInteractive(49-90)runInteractiveMenu(11-43)src/darwinkit/lib/format.ts (1)
defaultFormat(9-11)
🪛 LanguageTool
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[uncategorized] ~19-~19: The operating system from Apple is written “macOS”.
Context: ...scz/darwinkitdirectly — it only callssrc/utils/macos/` utils. Phase 1 expands utils to cover...
(MAC_OS)
[uncategorized] ~23-~23: The operating system from Apple is written “macOS”.
Context: ...Phase 1: Expand Utils ### New files in src/utils/macos/: auth.ts — Biometric authentic...
(MAC_OS)
.claude/plans/2026-03-12-DarwinKitCLI.md
[uncategorized] ~7-~7: The operating system from Apple is written “macOS”.
Context: ...Architecture:* Two phases: (1) Expand src/utils/macos/ with missing util wrappers (auth, sys...
(MAC_OS)
[uncategorized] ~46-~46: The operating system from Apple is written “macOS”.
Context: ...pes.ts** Add to the re-export block in src/utils/macos/types.ts: ```typescript export type {...
(MAC_OS)
[uncategorized] ~58-~58: The operating system from Apple is written “macOS”.
Context: ...ep 3: Add exports to index.ts** Add to src/utils/macos/index.ts: ```typescript // Auth expor...
(MAC_OS)
[uncategorized] ~75-~75: The operating system from Apple is written “macOS”.
Context: ...etryType, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors **Step 5: Comm...
(MAC_OS)
[uncategorized] ~133-~133: The operating system from Apple is written “macOS”.
Context: ...pability, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors **Step 5: Comm...
(MAC_OS)
[uncategorized] ~288-~288: The operating system from Apple is written “macOS”.
Context: ...usResult, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors Run: `bunx bio...
(MAC_OS)
[uncategorized] ~1571-~1571: The operating system from Apple is written “macOS”.
Context: ...rwinkit/ Step 2: Biome check Run: bunx biome check src/darwinkit/ src/utils/macos/ Expected: zero errors **Step 3: Full...
(MAC_OS)
🪛 markdownlint-cli2 (0.21.0)
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (10)
src/utils/macos/auth.ts (1)
1-17: LGTM!Clean, well-typed wrapper functions that properly delegate to the DarwinKit auth API. The optional
reasonparameter is correctly handled with the conditional object construction.src/utils/macos/system.ts (1)
1-9: LGTM!Simple, well-typed wrapper for system capabilities. Clean delegation pattern consistent with other macOS utilities.
src/darwinkit/lib/format.ts (1)
1-142: LGTM!Well-structured output formatting module with clear separation between raw, pretty, and JSON modes. Good use of
picocolorsfor terminal coloring as per project conventions. The heuristic value extraction informatRawfor common result shapes (text,contentfields) is a practical approach for CLI output.src/darwinkit/index.ts (1)
156-181: LGTM!The main function properly handles TTY detection for interactive vs non-interactive modes. Error handling is consistent and includes proper cleanup via
closeDarwinKit().src/darwinkit/lib/interactive.ts (1)
49-90: LGTM!The interactive command execution flow is well-structured: displays usage hint, prompts for missing params, shows spinner during execution, and properly formats output. Error handling and cleanup via
closeDarwinKit()are correctly implemented.src/utils/macos/index.ts (1)
1-103: LGTM!Clean barrel file organization with logical grouping of exports. The new auth, iCloud, and system utilities are appropriately placed in the macOS utils module, and the type exports are comprehensive.
src/utils/macos/types.ts (1)
1-106: LGTM!Clean type organization with re-exports from
@genesiscz/darwinkitand well-documented local types. Consolidating theNeighbortype to use the external package definition is a good consistency improvement.src/darwinkit/lib/commands.ts (3)
39-62: LGTM!Well-designed type interfaces for the command registry.
ParamDefcovers all necessary metadata for driving help, validation, and interactive prompts.CommandDefprovides a clean contract for command implementations.
81-547: LGTM!Comprehensive command registry covering all 8 groups with consistent patterns. Each command properly delegates to the corresponding macOS utility functions with appropriate argument transformation. The batch text-analysis commands correctly transform
string[]inputs to the requiredTextItem[]format.
550-571: LGTM!Clean utility functions for command lookup and grouping.
getCommandsByGroup()correctly initializes all groups fromGROUP_ORDERbefore populating, ensuring consistent iteration order and inclusion of potentially empty groups.
genesiscz
added a commit
that referenced
this pull request
Mar 12, 2026
- Add return after sub.outputHelp() for explicit process exit (t1/t6) - Fix icloudList doc to reflect flat ICloudDirEntry[] return (t2) - Add missing commands: classify-batch, group-by-category, icloud-write-bytes, icloud-start-monitoring, icloud-stop-monitoring (t3) - Split comma-separated string[] args and validate numeric input (t4) - Forward --format flag to interactive fallback (t5) - Validate --format option values (t7) - Handle empty string for string[] interactive params (t8) - Add onIcloudFilesChanged subscription wrapper (t9)
genesiscz
commented
Mar 12, 2026
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
♻️ Duplicate comments (1)
src/darwinkit/lib/interactive.ts (1)
131-147:⚠️ Potential issue | 🟠 MajorEmpty
string[]answers still break required/default handling.At Line 140, every blank response becomes
[]. That lets required array params run with no values, and it drops defaults for optional array params likeschemesandlanguagesinstead of preserving them. As per coding guidelines, "Provide sensible defaults and suggestions in user prompts".Suggested fix
if (param.type === "string[]") { const result = await withCancel( p.text({ message: `${param.name} ${pc.dim(`(${param.description}, comma-separated)`)}`, placeholder: param.default ? String(param.default) : undefined, + validate: (v) => { + if (param.required && v.trim() === "") { + return `${param.name} is required`; + } + }, }) ); const str = (result as string).trim(); if (str === "") { - return []; + return Array.isArray(param.default) ? param.default : []; } return str .split(",") .map((s) => s.trim())🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/lib/interactive.ts` around lines 131 - 147, When handling param.type === "string[]" don't unconditionally convert a blank response to []: if the trimmed input is empty, return param.default (coerced to string[] if present); if no default and param.required is true, re-prompt (loop using p.text wrapped by withCancel until a non-empty response is given); otherwise (not required and no default) return []. Update the branch around the withCancel(p.text(...)) call to implement this logic and ensure you reference param.name, param.default, param.required, p.text and withCancel so defaults and required validation are preserved.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/plans/2026-03-12-DarwinKitCLI-design.md:
- Around line 128-129: The piped example fails because the detect-language
subcommand still requires the positional argument named text; update the
detect-language command handler so that the positional parameter text is
optional and, if undefined, the handler reads from stdin (consume process.stdin
until EOF) and uses that value as text before proceeding; ensure the command
registration for detect-language allows an optional text argument and that any
validation/usage logic accepts stdin-derived text so the piped example works as
documented.
In `@src/darwinkit/index.ts`:
- Around line 154-155: The current invocation prints help via sub.outputHelp()
and then calls process.exit(0), which incorrectly signals success for an
invocation error; change this to exit with a non-zero status (e.g.,
process.exit(1)) or throw an error instead so shells/CI treat missing required
args as failure—update the code path that calls sub.outputHelp() and
process.exit(0) to use process.exit(1) (or raise an Error) so tools darwinkit
<cmd> returns a non-zero exit code on missing arguments.
- Around line 147-150: The interactive branch uses the raw opts.format string
cast to OutputFormat and can pass invalid values into
runCommandInteractive/formatOutput; validate/sanitize opts.format the same way
as the non-interactive path before calling runCommandInteractive (e.g., convert
or map opts.format to a known OutputFormat or set to undefined if invalid) so
that runCommandInteractive receives only a valid OutputFormat or undefined;
update the code around process.stdout.isTTY / p.intro to reuse the existing
format validation logic for fmtOpt before calling runCommandInteractive.
- Around line 131-145: When handling param.type === "string[]", ensure you
normalize both string and array inputs by splitting comma-separated elements
from any array entries (e.g., if rawValue is an array like ["a,b"] or ["a","b"])
— use Array.isArray(rawValue) and split each element on commas, trim and filter
blanks, and set args[param.name] to that flattened array; then update the
required-parameter check (the missing calculation that iterates cmd.params) to
treat empty arrays as missing as well by marking a param missing when
args[pm.name] === undefined OR (Array.isArray(args[pm.name]) &&
args[pm.name].length === 0). This ensures variadic options accept
comma-separated strings and required array params fail validation when empty.
In `@src/darwinkit/lib/interactive.ts`:
- Around line 85-90: The catch block currently logs the error (spin.stop,
p.log.error) but swallows it, allowing a zero exit; update the handler in
interactive.ts so after logging the failure for cmd.name you set a non-zero exit
code (e.g. process.exitCode = 1) to preserve failure for interactive/TTY runs
and then proceed to closeDarwinKit() in finally; ensure you still stop the
spinner (spin.stop) and log the original error (p.log.error(error instanceof
Error ? error.message : String(error))) before setting process.exitCode.
In `@src/utils/macos/icloud.ts`:
- Around line 75-78: The docstring is pointing callers to
getDarwinKit().icloud.onFilesChanged but the public API now exposes
onIcloudFilesChanged; update the comment above the monitoring function to tell
users to call the exported wrapper onIcloudFilesChanged(handler) (and remove or
replace the getDarwinKit().icloud reference), keeping the same explanation about
starting iCloud Drive monitoring and how to listen for file changes.
---
Duplicate comments:
In `@src/darwinkit/lib/interactive.ts`:
- Around line 131-147: When handling param.type === "string[]" don't
unconditionally convert a blank response to []: if the trimmed input is empty,
return param.default (coerced to string[] if present); if no default and
param.required is true, re-prompt (loop using p.text wrapped by withCancel until
a non-empty response is given); otherwise (not required and no default) return
[]. Update the branch around the withCancel(p.text(...)) call to implement this
logic and ensure you reference param.name, param.default, param.required, p.text
and withCancel so defaults and required validation are preserved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 07c6e93e-51b2-448f-9280-b7e821ad4246
📒 Files selected for processing (6)
.claude/plans/2026-03-12-DarwinKitCLI-design.mdsrc/darwinkit/index.tssrc/darwinkit/lib/commands.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.ts: Usebun runto execute TypeScript files directly without a build step
Place general-purpose helper functions insrc/utils/instead of tool directories
Never add// src/path/to/file.tsas the first line of files
Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Always use block form with braces forifstatements, even for early returns; never use one-lineifstatements
Add an empty line beforeifstatements unless the preceding line is a variable declaration used by thatif
Add an empty line after closing}unless followed byelse,catch,finally, or another}
Noas anytype assertions; use proper type narrowing, type guards, or explicit interfaces instead
Use discriminant checks (e.g.,entity.className === "User") when working with union types instead of type assertions
Prefererror: errovererror: err instanceof Error ? err.message : String(err)when the error field accepts unknown type
Files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
src/**/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/index.ts: Usecommanderfor parsing command-line arguments with subcommands and options
Support multiple output destinations (file, clipboard, stdout) and useclipboardyfor clipboard operations
Tool discovery checks for directories withindex.tsorindex.tsx(tool name = directory name) and standalone.tsor.tsxfiles (tool name = filename without extension)
Respect--silentand--verboseflags in tool output handling
Files:
src/darwinkit/index.tssrc/utils/macos/index.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.ts: Use@clack/promptsfor interactive user prompts (preferred over@inquirer/prompts)
UseBun.spawn()for executing external commands and always check exit codes with meaningful error messages
Use Node.jspathmodule for cross-platform path handling and resolve relative paths to absolute usingresolve()
Use Bun's native file APIs (Bun.write()) for better performance instead of other file writing methods
Use centralized logging with pino logger outputting to/logs/directory organized by date
Handle user cancellation from prompts gracefully
Provide sensible defaults and suggestions in user prompts
Strip ANSI codes fromchalkcolored output for non-TTY environments
Files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
src/utils/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Check if a utility is general-purpose (usable by other tools) before deciding to place it in
src/utils/
Files:
src/utils/macos/icloud.tssrc/utils/macos/index.ts
🧠 Learnings (22)
📓 Common learnings
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Use `commander` for parsing command-line arguments with subcommands and options
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/commands.ts
📚 Learning: 2026-03-12T03:48:42.474Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In TypeScript files that use Commander subcommands and exit after showing help, replace code after Command.help() with the pattern: call sub.outputHelp(); (returns void) followed by process.exit(0) or process.exit(1). This avoids TS7027 unreachable-code because Command.help() returns never. Apply this pattern in all src/**/*.ts files where subcommands need to display help before exiting.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation in all non-config boundaries (API responses, JSONL, cache, subprocess output). The 3-arg form SafeJSON.parse(text, null, { strict: true }) is invalid and should not be used. Only lenient default (no options) is appropriate for user-authored config files that may contain comments/trailing commas. Apply this guideline across TypeScript files (src/**/*.ts) wherever SafeJSON.parse is used.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:31.309Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/claude/auth.ts:0-0
Timestamp: 2026-03-12T01:26:31.309Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). There is no separate third `options` argument. Use `SafeJSON.parse(text, { strict: true })` at external/API/subprocess/JSONL/cache-file boundaries so malformed data fails fast with strict RFC 8259 validation. Use the lenient default (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-02-24T15:39:24.751Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:182-210
Timestamp: 2026-02-24T15:39:24.751Z
Learning: In src/github/, output formatting uses separate functions for different modes: formatReviewTerminal() for colored terminal output, formatReviewMarkdown() for markdown files, and formatReviewJSON() for JSON. The caller selects the appropriate formatter based on output mode flags. Do not suggest adding TTY detection to individual formatters, as the architecture handles this through formatter separation.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:21.929Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/macos/lib/mail/jxa.ts:0-0
Timestamp: 2026-03-12T01:26:21.929Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. There is NO 3-argument overload — do NOT suggest `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at all remote/third-party API response boundaries, JSONL parsing points, subprocess stdout, and cache files; reserve lenient default (no second arg) only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:40.712Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/timelog/import.ts:0-0
Timestamp: 2026-03-12T01:26:40.712Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is overloaded: pass a function for a reviver, or pass `{ strict: true }` / `{ jsonl: true }` as a `ParseOptions` object to delegate to native `JSON.parse`. The correct strict-mode call is `SafeJSON.parse(text, { strict: true })` — NOT the 3-arg form `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output. Reserve the lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:31.610Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/timely/utils/entry-processor.ts:0-0
Timestamp: 2026-03-12T01:26:31.610Z
Learning: In code paths where JSON is consumed, prefer strict RFC 8259 validation by using SafeJSON.parse(text, { strict: true }) instead of the lenient default. Apply this at non-config boundaries (e.g., API responses, JSONL, cache outputs, subprocess outputs). Reserve the lenient comment-json behavior only for user-authored config files that may legitimately contain comments or trailing commas. For src/timely/utils/entry-processor.ts and similar modules, replace or wrap JSON parsing with SafeJSON.parse(text, { strict: true }) unless you are explicitly handling config files that require comments.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:31.667Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/clarity/api.ts:0-0
Timestamp: 2026-03-12T01:26:31.667Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object (e.g. `{ strict: true }`). Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries (e.g. Clarity API, Timely API, Azure DevOps API) and JSONL/subprocess-output parsing points so malformed or non-standard responses fail fast. Fall back to the lenient default (no second arg, or `null`) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:25.817Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/hold-ai/client.ts:0-0
Timestamp: 2026-03-12T01:26:25.817Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). To enable strict RFC 8259 validation (delegating to native `JSON.parse`), use `SafeJSON.parse(text, { strict: true })` — there is no separate third `options` parameter. Apply `{ strict: true }` at all non-config boundaries: API responses, JSONL parsing, cache files, and subprocess output. Reserve lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-09T13:13:58.786Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:13:58.786Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), do not treat CI formatter warnings as enforceable formatting rules for TypeScript files under src/. Focus reviews on logical correctness and consistency with existing code patterns. For files under src (e.g., src/github/commands/get.ts), prioritize code structure, readability, naming, correctness, and adherence to project conventions over automated formatting warnings from CI tools.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-20T00:52:27.023Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 31
File: src/ask/utils/helpers.ts:3-3
Timestamp: 2026-02-20T00:52:27.023Z
Learning: In all TypeScript source files under src, prefer using picocolors for colored terminal output in new code. Picocolors is smaller and faster than chalk, so adopt it for CLI output coloring and avoid adding chalk in new code paths unless there is a compelling compatibility reason.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-24T15:32:37.494Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/output.ts:109-113
Timestamp: 2026-02-24T15:32:37.494Z
Learning: In TypeScript files under src/, do not require a leading blank line before an if statement that is the first statement inside a function body (immediately after the function signature). The blank line rule should only apply to if statements that come after other statements within the function body. Apply this guideline consistently across TS files in src to reduce unnecessary vertical whitespace and keep concise function bodies.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In GenesisTools, apply a no-obvious-comments rule: do not add inline comments for well-known POSIX patterns or standard idioms (e.g., a process.kill(pid, 0) probe) when surrounding code is self-documenting through descriptive function/variable names. This guidance applies to TypeScript files under src (src/**/*.ts). Only include comments if they add non-obvious rationale, edge-case behavior, or explain complex logic that cannot be inferred from code alone.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-24T15:32:44.925Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:18-20
Timestamp: 2026-02-24T15:32:44.925Z
Learning: In TypeScript files, do not require a blank line between the opening brace of a function and the first statement if the first statement is the if statement immediately after the signature. The blank-line rule applies to separating an if from unrelated preceding code within the same block, not to spacing after the function opening brace. Apply this rule to all TS functions across the codebase.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:18.985Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/claude/lib/history/search.ts:0-0
Timestamp: 2026-03-12T01:26:18.985Z
Learning: When using SafeJSON.parse in TypeScript code, prefer the two-argument form SafeJSON.parse(text, { strict: true }) to enable strict RFC 8259 validation via the native JSON.parse. Do NOT use the three-argument form SafeJSON.parse(text, null, { strict: true }). Apply strict parsing at remote/third-party API boundaries, JSONL parsing points, and subprocess output. Fall back to the lenient/default form only for user-authored config files that may legitimately contain comments or trailing commas. This pattern keeps strict validation where appropriate and preserves leniency for internal/config data.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In the genesiscz/GenesisTools repository, prefer using SafeJSON.parse(text, { strict: true }) (2-argument form) at all non-config JSON boundaries such as API responses, JSONL parsers, cache files, and subprocess stdout. Reserve the lenient default (SafeJSON.parse(text) with no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In GenesisTools, ensure SafeJSON.parse is called with exactly two arguments. Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation, or pass a reviver function as the second argument. Do not call SafeJSON.parse(text, null, { strict: true }) since the function signature does not support a three-argument form. Apply this guideline to all TypeScript files that use SafeJSON.parse (e.g., src/utils/json.ts) and other related code.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/lib/commands.tssrc/utils/macos/icloud.tssrc/utils/macos/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `clack/prompts` for interactive user prompts (preferred over `inquirer/prompts`)
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: The `tools` executable shows an interactive tool selector using inquirer/prompts when run without arguments
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-02-17T01:37:29.373Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 29
File: .claude/plans/2026-02-16-ClaudeHistory-SummarizeMemorize-Implementation.md:11-15
Timestamp: 2026-02-17T01:37:29.373Z
Learning: Do not apply markdownlint to files under the .claude/ directory. This exemption covers design documents, plans, and archived content within .claude/ (e.g., .claude/plans/.../*.md). Treat these files as exempt from markdownlint rules to avoid false positives on non-standard or archival content.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI-design.md
🧬 Code graph analysis (1)
src/utils/macos/icloud.ts (1)
src/utils/macos/index.ts (18)
icloudStatus(16-16)ICloudStatusResult(85-85)getDarwinKit(6-6)icloudRead(14-14)ICloudReadResult(84-84)icloudWrite(18-18)ICloudOkResult(83-83)icloudWriteBytes(19-19)icloudDelete(10-10)icloudMove(13-13)icloudCopy(9-9)icloudList(11-11)ICloudDirEntry(81-81)ICloudListDirResult(82-82)icloudMkdir(12-12)icloudStartMonitoring(15-15)icloudStopMonitoring(17-17)onIcloudFilesChanged(20-20)
🪛 LanguageTool
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[uncategorized] ~19-~19: The operating system from Apple is written “macOS”.
Context: ...scz/darwinkitdirectly — it only callssrc/utils/macos/` utils. Phase 1 expands utils to cover...
(MAC_OS)
[uncategorized] ~23-~23: The operating system from Apple is written “macOS”.
Context: ...Phase 1: Expand Utils ### New files in src/utils/macos/: auth.ts — Biometric authentic...
(MAC_OS)
🪛 markdownlint-cli2 (0.21.0)
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
Comment on lines
+128
to
+129
| # Piped | ||
| echo "Hello world" | tools darwinkit detect-language --format json | jq .language |
Contributor
There was a problem hiding this comment.
The piped example advertises stdin support that the CLI does not implement.
detect-language still requires the positional text argument. In the current implementation, this invocation prints subcommand help instead of consuming piped stdin, so the example will fail as written.
Suggested fix
-echo "Hello world" | tools darwinkit detect-language --format json | jq .language
+tools darwinkit detect-language "Hello world" --format json | jq .language📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Piped | |
| echo "Hello world" | tools darwinkit detect-language --format json | jq .language | |
| # Piped | |
| tools darwinkit detect-language "Hello world" --format json | jq .language |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/plans/2026-03-12-DarwinKitCLI-design.md around lines 128 - 129, The
piped example fails because the detect-language subcommand still requires the
positional argument named text; update the detect-language command handler so
that the positional parameter text is optional and, if undefined, the handler
reads from stdin (consume process.stdin until EOF) and uses that value as text
before proceeding; ensure the command registration for detect-language allows an
optional text argument and that any validation/usage logic accepts stdin-derived
text so the piped example works as documented.
genesiscz
added a commit
that referenced
this pull request
Mar 12, 2026
- Add return after sub.outputHelp() for explicit process exit (t1/t6) - Fix icloudList doc to reflect flat ICloudDirEntry[] return (t2) - Add missing commands: classify-batch, group-by-category, icloud-write-bytes, icloud-start-monitoring, icloud-stop-monitoring (t3) - Split comma-separated string[] args and validate numeric input (t4) - Forward --format flag to interactive fallback (t5) - Validate --format option values (t7) - Handle empty string for string[] interactive params (t8) - Add onIcloudFilesChanged subscription wrapper (t9)
genesiscz
force-pushed
the
feat/darwinkit-utils
branch
from
bcff54b to
f51c520
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (4)
src/darwinkit/index.ts (3)
131-145:⚠️ Potential issue | 🔴 CriticalNormalize variadic
string[]options before validating required params.
<values...>options arrive as arrays, so inputs like--items "a,b"currently stay as["a,b"]instead of["a", "b"]. The required-param check also treats[]as present, which lets empty array args through for commands likerank,batch-sentiment, andclassify-batch.Suggested fix
} else if (param.type === "string[]") { - args[param.name] = - typeof rawValue === "string" - ? rawValue - .split(",") - .map((s: string) => s.trim()) - .filter(Boolean) - : rawValue; + args[param.name] = (Array.isArray(rawValue) ? rawValue : [rawValue]) + .flatMap((value) => String(value).split(",")) + .map((value) => value.trim()) + .filter(Boolean); } else { args[param.name] = rawValue; } } - const missing = cmd.params.filter((pm) => pm.required && args[pm.name] === undefined); + const missing = cmd.params.filter((pm) => { + if (!pm.required) { + return false; + } + + const value = args[pm.name]; + return value === undefined || (Array.isArray(value) && value.length === 0); + });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/index.ts` around lines 131 - 145, The variadic "string[]" handling in the param parsing (when param.type === "string[]") must normalize both string and array inputs and ensure empty arrays are treated as missing for required checks: when rawValue is a string split on commas, trim and filter empties (current behavior), and when rawValue is an array, flatten any comma-separated elements by splitting each element, trimming and filtering, then assign the resulting array to args[param.name]; finally, ensure the later required check (cmd.params.filter(... args[pm.name] === undefined) ) treats empty arrays as undefined by setting args[param.name] = undefined if the normalized array.length === 0 so required params like rank/batch-sentiment/classify-batch fail validation correctly.
147-150:⚠️ Potential issue | 🟡 MinorReuse the sanitized format in the interactive fallback.
This branch forwards
opts.formatthrough a cast, so--format foocan still reachrunCommandInteractive()even though the non-interactive path validates the same option.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/index.ts` around lines 147 - 150, The interactive branch is passing opts.format via a cast (fmtOpt) which allows invalid values to reach runCommandInteractive; change it to use the same sanitized/validated format value used by the non-interactive path (replace the casted fmtOpt with the previously-validated format variable) so runCommandInteractive receives the validated OutputFormat; update the call to runCommandInteractive(cmd, args, <validatedFormat> as OutputFormat | undefined) and remove the opts.format cast.
154-155:⚠️ Potential issue | 🟠 MajorReturn a non-zero exit code for missing required arguments.
This is an invocation error, not a successful help display. Exiting
0makes shells and CI treattools darwinkit <cmd>with missing required params as success.Suggested fix
sub.outputHelp(); - process.exit(0); + process.exit(1);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/index.ts` around lines 154 - 155, sub.outputHelp() is being followed by process.exit(0), which signals success for an invocation error; change the exit to a non-zero code. Replace the process.exit(0) call (the code path that shows help for missing required arguments) with a non-zero exit (e.g., process.exit(1) or set process.exitCode = 1 before exiting) so the CLI returns a failure status when required params are missing; update the code around sub.outputHelp() and process.exit accordingly.src/darwinkit/lib/interactive.ts (1)
85-90:⚠️ Potential issue | 🟠 MajorPreserve a failing exit status for interactive runs.
This catch block logs the error and then returns normally, so interactive failures can still exit with status
0.Suggested fix
} catch (error) { spin.stop(pc.red(`${cmd.name} failed`)); p.log.error(error instanceof Error ? error.message : String(error)); + process.exitCode = 1; } finally { closeDarwinKit(); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/lib/interactive.ts` around lines 85 - 90, The catch block in the interactive run swallows errors (in the try/catch where spin.stop and p.log.error are called), causing a zero exit code; after logging the error in that catch (the block that calls spin.stop(pc.red(`${cmd.name} failed`)) and p.log.error(...)), rethrow the original error (throw error) or explicitly exit with a non-zero status so failures propagate—ensure this change occurs before closeDarwinKit() is called or rethrow after cleanup so interactive.ts preserves a failing exit status.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/plans/2026-03-12-DarwinKitCLI.md:
- Around line 229-243: The plan's icloud.ts is missing the subscription wrapper
present in the real implementation: add an onIcloudFilesChanged function that
exposes the underlying subscription API by calling
getDarwinKit().icloud.onFilesChanged(handler) (matching the naming and semantics
of the real implementation) so the plan reflects the full API surface alongside
the existing icloudStartMonitoring and icloudStopMonitoring functions.
- Around line 947-1029: The plan's iCloud command registry is missing entries
for the new commands added in code—add registry entries for icloud-write-bytes,
icloud-start-monitoring, and icloud-stop-monitoring to match the implementation;
include each command name, group "icloud", a short description, appropriate
params (e.g., path/bytes for icloud-write-bytes and none for monitoring
commands) and run handlers pointing to icloudWriteBytes, icloudStartMonitoring,
and icloudStopMonitoring respectively so the plan and code stay in sync.
- Around line 1127-1170: Update the stale runCommandInteractive signature to
accept the new formatOverride parameter and thread it through so the user's
--format choice is preserved: change the function signature for
runCommandInteractive(cmd: CommandDef, providedArgs: Record<string, unknown> =
{}, formatOverride?: string) to include formatOverride, keep prompting logic
(promptForParam, buildUsageLine) unchanged, then use format =
defaultFormat(formatOverride) or otherwise pass formatOverride into whatever
defaultFormat/formatOutput call is used so the selected format is honored when
calling formatOutput(result, format), and update any call sites of
runCommandInteractive accordingly; ensure closeDarwinKit, spinner logic, and
error handling remain the same.
- Around line 1466-1469: Replace the unreachable call pattern using sub.help()
followed by return: Command.help() is typed as never so the subsequent return
triggers TS7027; update the non-TTY branch to call sub.outputHelp() and then
explicitly call process.exit(0) (i.e., replace sub.help() / return with
sub.outputHelp(); process.exit(0)) so the control flow and types are correct.
---
Duplicate comments:
In `@src/darwinkit/index.ts`:
- Around line 131-145: The variadic "string[]" handling in the param parsing
(when param.type === "string[]") must normalize both string and array inputs and
ensure empty arrays are treated as missing for required checks: when rawValue is
a string split on commas, trim and filter empties (current behavior), and when
rawValue is an array, flatten any comma-separated elements by splitting each
element, trimming and filtering, then assign the resulting array to
args[param.name]; finally, ensure the later required check
(cmd.params.filter(... args[pm.name] === undefined) ) treats empty arrays as
undefined by setting args[param.name] = undefined if the normalized array.length
=== 0 so required params like rank/batch-sentiment/classify-batch fail
validation correctly.
- Around line 147-150: The interactive branch is passing opts.format via a cast
(fmtOpt) which allows invalid values to reach runCommandInteractive; change it
to use the same sanitized/validated format value used by the non-interactive
path (replace the casted fmtOpt with the previously-validated format variable)
so runCommandInteractive receives the validated OutputFormat; update the call to
runCommandInteractive(cmd, args, <validatedFormat> as OutputFormat | undefined)
and remove the opts.format cast.
- Around line 154-155: sub.outputHelp() is being followed by process.exit(0),
which signals success for an invocation error; change the exit to a non-zero
code. Replace the process.exit(0) call (the code path that shows help for
missing required arguments) with a non-zero exit (e.g., process.exit(1) or set
process.exitCode = 1 before exiting) so the CLI returns a failure status when
required params are missing; update the code around sub.outputHelp() and
process.exit accordingly.
In `@src/darwinkit/lib/interactive.ts`:
- Around line 85-90: The catch block in the interactive run swallows errors (in
the try/catch where spin.stop and p.log.error are called), causing a zero exit
code; after logging the error in that catch (the block that calls
spin.stop(pc.red(`${cmd.name} failed`)) and p.log.error(...)), rethrow the
original error (throw error) or explicitly exit with a non-zero status so
failures propagate—ensure this change occurs before closeDarwinKit() is called
or rethrow after cleanup so interactive.ts preserves a failing exit status.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5d58a10e-5f4d-4561-b0bd-fc78c470f848
📒 Files selected for processing (11)
.claude/plans/2026-03-12-DarwinKitCLI-design.md.claude/plans/2026-03-12-DarwinKitCLI.mdsrc/darwinkit/index.tssrc/darwinkit/lib/commands.tssrc/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/auth.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/system.tssrc/utils/macos/types.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.ts: Usebun runto execute TypeScript files directly without a build step
Place general-purpose helper functions insrc/utils/instead of tool directories
Never add// src/path/to/file.tsas the first line of files
Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Always use block form with braces forifstatements, even for early returns; never use one-lineifstatements
Add an empty line beforeifstatements unless the preceding line is a variable declaration used by thatif
Add an empty line after closing}unless followed byelse,catch,finally, or another}
Noas anytype assertions; use proper type narrowing, type guards, or explicit interfaces instead
Use discriminant checks (e.g.,entity.className === "User") when working with union types instead of type assertions
Prefererror: errovererror: err instanceof Error ? err.message : String(err)when the error field accepts unknown type
Files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.ts: Use@clack/promptsfor interactive user prompts (preferred over@inquirer/prompts)
UseBun.spawn()for executing external commands and always check exit codes with meaningful error messages
Use Node.jspathmodule for cross-platform path handling and resolve relative paths to absolute usingresolve()
Use Bun's native file APIs (Bun.write()) for better performance instead of other file writing methods
Use centralized logging with pino logger outputting to/logs/directory organized by date
Handle user cancellation from prompts gracefully
Provide sensible defaults and suggestions in user prompts
Strip ANSI codes fromchalkcolored output for non-TTY environments
Files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
src/utils/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Check if a utility is general-purpose (usable by other tools) before deciding to place it in
src/utils/
Files:
src/utils/macos/types.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
src/**/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/index.ts: Usecommanderfor parsing command-line arguments with subcommands and options
Support multiple output destinations (file, clipboard, stdout) and useclipboardyfor clipboard operations
Tool discovery checks for directories withindex.tsorindex.tsx(tool name = directory name) and standalone.tsor.tsxfiles (tool name = filename without extension)
Respect--silentand--verboseflags in tool output handling
Files:
src/darwinkit/index.tssrc/utils/macos/index.ts
🧠 Learnings (39)
📓 Common learnings
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
📚 Learning: 2026-02-24T15:39:24.751Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:182-210
Timestamp: 2026-02-24T15:39:24.751Z
Learning: In src/github/, output formatting uses separate functions for different modes: formatReviewTerminal() for colored terminal output, formatReviewMarkdown() for markdown files, and formatReviewJSON() for JSON. The caller selects the appropriate formatter based on output mode flags. Do not suggest adding TTY detection to individual formatters, as the architecture handles this through formatter separation.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/index.ts
📚 Learning: 2026-02-20T00:52:27.023Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 31
File: src/ask/utils/helpers.ts:3-3
Timestamp: 2026-02-20T00:52:27.023Z
Learning: In all TypeScript source files under src, prefer using picocolors for colored terminal output in new code. Picocolors is smaller and faster than chalk, so adopt it for CLI output coloring and avoid adding chalk in new code paths unless there is a compelling compatibility reason.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-02-24T15:32:37.494Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/output.ts:109-113
Timestamp: 2026-02-24T15:32:37.494Z
Learning: In TypeScript files under src/, do not require a leading blank line before an if statement that is the first statement inside a function body (immediately after the function signature). The blank line rule should only apply to if statements that come after other statements within the function body. Apply this guideline consistently across TS files in src to reduce unnecessary vertical whitespace and keep concise function bodies.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-09T13:13:58.786Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:13:58.786Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), do not treat CI formatter warnings as enforceable formatting rules for TypeScript files under src/. Focus reviews on logical correctness and consistency with existing code patterns. For files under src (e.g., src/github/commands/get.ts), prioritize code structure, readability, naming, correctness, and adherence to project conventions over automated formatting warnings from CI tools.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:26:31.610Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/timely/utils/entry-processor.ts:0-0
Timestamp: 2026-03-12T01:26:31.610Z
Learning: In code paths where JSON is consumed, prefer strict RFC 8259 validation by using SafeJSON.parse(text, { strict: true }) instead of the lenient default. Apply this at non-config boundaries (e.g., API responses, JSONL, cache outputs, subprocess outputs). Reserve the lenient comment-json behavior only for user-authored config files that may legitimately contain comments or trailing commas. For src/timely/utils/entry-processor.ts and similar modules, replace or wrap JSON parsing with SafeJSON.parse(text, { strict: true }) unless you are explicitly handling config files that require comments.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In GenesisTools, apply a no-obvious-comments rule: do not add inline comments for well-known POSIX patterns or standard idioms (e.g., a process.kill(pid, 0) probe) when surrounding code is self-documenting through descriptive function/variable names. This guidance applies to TypeScript files under src (src/**/*.ts). Only include comments if they add non-obvious rationale, edge-case behavior, or explain complex logic that cannot be inferred from code alone.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-02-24T15:32:44.925Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:18-20
Timestamp: 2026-02-24T15:32:44.925Z
Learning: In TypeScript files, do not require a blank line between the opening brace of a function and the first statement if the first statement is the if statement immediately after the signature. The blank-line rule applies to separating an if from unrelated preceding code within the same block, not to spacing after the function opening brace. Apply this rule to all TS functions across the codebase.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation in all non-config boundaries (API responses, JSONL, cache, subprocess output). The 3-arg form SafeJSON.parse(text, null, { strict: true }) is invalid and should not be used. Only lenient default (no options) is appropriate for user-authored config files that may contain comments/trailing commas. Apply this guideline across TypeScript files (src/**/*.ts) wherever SafeJSON.parse is used.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:26:18.985Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/claude/lib/history/search.ts:0-0
Timestamp: 2026-03-12T01:26:18.985Z
Learning: When using SafeJSON.parse in TypeScript code, prefer the two-argument form SafeJSON.parse(text, { strict: true }) to enable strict RFC 8259 validation via the native JSON.parse. Do NOT use the three-argument form SafeJSON.parse(text, null, { strict: true }). Apply strict parsing at remote/third-party API boundaries, JSONL parsing points, and subprocess output. Fall back to the lenient/default form only for user-authored config files that may legitimately contain comments or trailing commas. This pattern keeps strict validation where appropriate and preserves leniency for internal/config data.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In the genesiscz/GenesisTools repository, prefer using SafeJSON.parse(text, { strict: true }) (2-argument form) at all non-config JSON boundaries such as API responses, JSONL parsers, cache files, and subprocess stdout. Reserve the lenient default (SafeJSON.parse(text) with no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In GenesisTools, ensure SafeJSON.parse is called with exactly two arguments. Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation, or pass a reviver function as the second argument. Do not call SafeJSON.parse(text, null, { strict: true }) since the function signature does not support a three-argument form. Apply this guideline to all TypeScript files that use SafeJSON.parse (e.g., src/utils/json.ts) and other related code.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-03-12T03:48:42.474Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In TypeScript files that use Commander subcommands and exit after showing help, replace code after Command.help() with the pattern: call sub.outputHelp(); (returns void) followed by process.exit(0) or process.exit(1). This avoids TS7027 unreachable-code because Command.help() returns never. Apply this pattern in all src/**/*.ts files where subcommands need to display help before exiting.
Applied to files:
src/darwinkit/lib/format.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/types.tssrc/darwinkit/lib/commands.tssrc/darwinkit/index.tssrc/utils/macos/system.tssrc/utils/macos/icloud.tssrc/utils/macos/index.tssrc/utils/macos/auth.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `clack/prompts` for interactive user prompts (preferred over `inquirer/prompts`)
Applied to files:
src/darwinkit/lib/interactive.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-11T17:12:19.730Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/clarity/ui/src/routes/settings.tsx:1-1
Timestamp: 2026-03-11T17:12:19.730Z
Learning: In genesiscz/GenesisTools, `SafeJSON` in `src/utils/json.ts` intentionally uses `comment-json.parse` for parsing (to handle `//` comments, trailing commas, unquoted keys) but `JSON.stringify` (native) for stringification. Do not flag `SafeJSON.stringify` usages as unnecessary — the intent is a unified drop-in for `JSON` that parses leniently but serialises as standard JSON.
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.tssrc/utils/macos/icloud.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In genesiscz/GenesisTools, enforce `SafeJSON.parse(text, { strict: true })` (2-arg form) at all non-config boundaries: API responses, JSONL lines, machine-generated cache files (e.g. `workitem-*.json`), and subprocess stdout. Reserve lenient/default parsing (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-11T17:13:11.173Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/debugging-master/llm-log.ts:27-27
Timestamp: 2026-03-11T17:13:11.173Z
Learning: In genesiscz/GenesisTools, `src/utils/debugging-master/llm-log.ts` is intentionally self-contained with zero external dependencies (only Node.js builtins). Do not add imports from `app/utils/json` or any other internal module to this file. When native JSON methods must be used here, suppress the `noRestrictedGlobals` Biome rule with `// biome-ignore lint/style/noRestrictedGlobals: self-contained snippet with no external dependencies` on the specific line.
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-08T23:00:34.621Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 78
File: .claude/github/reviews/pr-74-2026-03-03T02-02-09.md:0-0
Timestamp: 2026-03-08T23:00:34.621Z
Learning: In the GenesisTools repository, files under the `.claude/github/reviews/` directory (e.g., `.claude/github/reviews/pr-74-2026-03-03T02-02-09.md`) are PR review artifacts that should NOT be committed to the repository. Flag any such files appearing in a PR diff as unrelated stray artifacts that should be removed from the branch/commit.
Applied to files:
src/darwinkit/lib/interactive.tssrc/utils/macos/icloud.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-09T13:39:43.059Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
Applied to files:
src/darwinkit/lib/interactive.ts.claude/plans/2026-03-12-DarwinKitCLI-design.mdsrc/darwinkit/index.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:26:31.309Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/claude/auth.ts:0-0
Timestamp: 2026-03-12T01:26:31.309Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). There is no separate third `options` argument. Use `SafeJSON.parse(text, { strict: true })` at external/API/subprocess/JSONL/cache-file boundaries so malformed data fails fast with strict RFC 8259 validation. Use the lenient default (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Handle user cancellation from prompts gracefully
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `Bun.spawn()` for executing external commands and always check exit codes with meaningful error messages
Applied to files:
src/darwinkit/lib/interactive.tssrc/darwinkit/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: The `tools` executable shows an interactive tool selector using inquirer/prompts when run without arguments
Applied to files:
src/darwinkit/lib/interactive.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Use `commander` for parsing command-line arguments with subcommands and options
Applied to files:
src/darwinkit/lib/commands.tssrc/darwinkit/index.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-11T14:37:42.310Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 87
File: docs/typescript-sdks/apple/github-repos-index.md:94-94
Timestamp: 2026-03-11T14:37:42.310Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), docs under `docs/typescript-sdks/apple/` (e.g., `github-repos-index.md`, `macos-node-api.md`) are auto-generated. Do not flag trivial markdown formatting issues (e.g., MD022 blank lines around headings, MD031, etc.) in these files, as they will not be manually fixed.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI-design.mdsrc/utils/macos/icloud.ts.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In genesiscz/GenesisTools (src/**/*.ts), do not add inline comments for well-known POSIX patterns or standard idioms (e.g., process.kill(pid, 0) probe) when the surrounding code is already self-documenting via descriptive function/variable names. The project enforces a no-obvious-comments rule: avoid comments that merely restate what the code clearly expresses.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI-design.md.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-02-17T01:37:29.373Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 29
File: .claude/plans/2026-02-16-ClaudeHistory-SummarizeMemorize-Implementation.md:11-15
Timestamp: 2026-02-17T01:37:29.373Z
Learning: Do not apply markdownlint to files under the .claude/ directory. This exemption covers design documents, plans, and archived content within .claude/ (e.g., .claude/plans/.../*.md). Treat these files as exempt from markdownlint rules to avoid false positives on non-standard or archival content.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI-design.md.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:26:21.929Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/macos/lib/mail/jxa.ts:0-0
Timestamp: 2026-03-12T01:26:21.929Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. There is NO 3-argument overload — do NOT suggest `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at all remote/third-party API response boundaries, JSONL parsing points, subprocess stdout, and cache files; reserve lenient default (no second arg) only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:40.712Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/timelog/import.ts:0-0
Timestamp: 2026-03-12T01:26:40.712Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is overloaded: pass a function for a reviver, or pass `{ strict: true }` / `{ jsonl: true }` as a `ParseOptions` object to delegate to native `JSON.parse`. The correct strict-mode call is `SafeJSON.parse(text, { strict: true })` — NOT the 3-arg form `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output. Reserve the lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:10.028Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/cache.ts:0-0
Timestamp: 2026-03-12T01:26:10.028Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is a union of reviver function or options object. When `{ strict: true }` is passed as the second argument, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries, JSONL parsing points, machine-written cache files, and subprocess output that need strict RFC 8259 validation. The lenient default (no second arg or `null`) is only appropriate for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:31.667Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/clarity/api.ts:0-0
Timestamp: 2026-03-12T01:26:31.667Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object (e.g. `{ strict: true }`). Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries (e.g. Clarity API, Timely API, Azure DevOps API) and JSONL/subprocess-output parsing points so malformed or non-standard responses fail fast. Fall back to the lenient default (no second arg, or `null`) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:07.205Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/api.ts:0-0
Timestamp: 2026-03-12T01:26:07.205Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). When `{ strict: true }` is passed, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` (NOT the 3-arg form with `null`) at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output that need strict RFC 8259 validation. Fall back to lenient default (no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Provide sensible defaults and suggestions in user prompts
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to **/*.ts : Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Applied to files:
src/darwinkit/index.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-24T22:38:46.781Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/watchman/index.ts:98-99
Timestamp: 2026-02-24T22:38:46.781Z
Learning: In src/watchman/index.ts, `as any` casts are necessary when calling fb-watchman Client methods (e.g., `client.command()`, `client.on("subscription", ...)`) because types/fb-watchman has incomplete type definitions. Using the local WatchmanResponse interface causes TS2769 errors. The biome-ignore comments document this justified exception to the general no-any guideline.
Applied to files:
src/utils/macos/icloud.ts
📚 Learning: 2026-03-12T03:48:42.474Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In the genesiscz/GenesisTools repo, Commander's `Command.help()` method is typed as `never` (it calls process.exit internally), so placing any statement after it (e.g., `return`) triggers TS7027 unreachable-code error. The idiomatic pattern for explicit, controlled exit in TypeScript is to use `sub.outputHelp()` (void-returning, just prints help) followed by `process.exit(0)` or `process.exit(1)`. Apply this pattern in all TypeScript files under src/ that use Commander subcommands and need to show help before exiting.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly 2 arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. To enable strict RFC 8259 validation (native JSON.parse), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. The 3-arg form `SafeJSON.parse(text, null, { strict: true })` is INCORRECT and does not exist. Use strict mode at all non-config boundaries: API responses, JSONL files, cache files, and subprocess output. Lenient default (no options) is only appropriate for user-authored config files that may contain comments or trailing commas.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In genesiscz/GenesisTools, use `SafeJSON.parse(text, { strict: true })` (2-arg form) at all non-config JSON boundaries: API responses, JSONL line parsers, cache files, and subprocess stdout. Reserve the lenient default (no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI.md
📚 Learning: 2026-03-09T13:14:03.722Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:14:03.722Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), there is no CI formatter (e.g., Prettier/Biome) configured or enforced. Do not flag formatting mismatches based on static analysis tool annotations (e.g., GitHub Actions CI formatter warnings) in this repository, as they are not representative of actual enforced formatting rules. TypeScript files under src/ should be reviewed for logical correctness and consistency with existing code patterns instead.
Applied to files:
.claude/plans/2026-03-12-DarwinKitCLI.md
🧬 Code graph analysis (4)
src/darwinkit/lib/format.ts (1)
src/utils/json.ts (1)
SafeJSON(24-58)
src/darwinkit/lib/interactive.ts (4)
src/darwinkit/lib/commands.ts (6)
getCommandsByGroup(637-653)GROUP_ORDER(82-82)GROUP_LABELS(71-80)commands(86-629)CommandDef(56-67)ParamDef(44-54)src/utils/prompts/clack/helpers.ts (4)
withCancel(27-33)p(77-77)isCancelled(12-14)handleCancel(19-22)src/darwinkit/lib/format.ts (1)
defaultFormat(9-11)src/utils/macos/index.ts (1)
closeDarwinKit(6-6)
src/darwinkit/index.ts (4)
src/utils/readme.ts (1)
handleReadmeFlag(14-32)src/darwinkit/lib/commands.ts (5)
getCommandsByGroup(637-653)GROUP_ORDER(82-82)GROUP_LABELS(71-80)commands(86-629)CommandDef(56-67)src/darwinkit/lib/interactive.ts (2)
runCommandInteractive(49-91)runInteractiveMenu(11-43)src/darwinkit/lib/format.ts (1)
defaultFormat(9-11)
src/utils/macos/auth.ts (2)
src/utils/macos/index.ts (5)
checkBiometry(2-2)AuthAvailableResult(71-71)getDarwinKit(6-6)authenticate(2-2)AuthenticateResult(72-72)src/utils/macos/types.ts (2)
AuthAvailableResult(3-3)AuthenticateResult(4-4)
🪛 LanguageTool
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[uncategorized] ~19-~19: The operating system from Apple is written “macOS”.
Context: ...scz/darwinkitdirectly — it only callssrc/utils/macos/` utils. Phase 1 expands utils to cover...
(MAC_OS)
[uncategorized] ~23-~23: The operating system from Apple is written “macOS”.
Context: ...Phase 1: Expand Utils ### New files in src/utils/macos/: auth.ts — Biometric authentic...
(MAC_OS)
.claude/plans/2026-03-12-DarwinKitCLI.md
[uncategorized] ~7-~7: The operating system from Apple is written “macOS”.
Context: ...Architecture:* Two phases: (1) Expand src/utils/macos/ with missing util wrappers (auth, sys...
(MAC_OS)
[uncategorized] ~46-~46: The operating system from Apple is written “macOS”.
Context: ...pes.ts** Add to the re-export block in src/utils/macos/types.ts: ```typescript export type {...
(MAC_OS)
[uncategorized] ~58-~58: The operating system from Apple is written “macOS”.
Context: ...ep 3: Add exports to index.ts** Add to src/utils/macos/index.ts: ```typescript // Auth expor...
(MAC_OS)
[uncategorized] ~75-~75: The operating system from Apple is written “macOS”.
Context: ...etryType, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors **Step 5: Comm...
(MAC_OS)
[uncategorized] ~133-~133: The operating system from Apple is written “macOS”.
Context: ...pability, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors **Step 5: Comm...
(MAC_OS)
[uncategorized] ~288-~288: The operating system from Apple is written “macOS”.
Context: ...usResult, ``` Step 4: Verify Run: tsgo --noEmit 2>&1 | rg "utils/macos" Expected: zero errors Run: `bunx bio...
(MAC_OS)
[uncategorized] ~1571-~1571: The operating system from Apple is written “macOS”.
Context: ...rwinkit/ Step 2: Biome check Run: bunx biome check src/darwinkit/ src/utils/macos/ Expected: zero errors **Step 3: Full...
(MAC_OS)
🪛 markdownlint-cli2 (0.21.0)
.claude/plans/2026-03-12-DarwinKitCLI-design.md
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
src/utils/macos/icloud.ts (2)
75-78: Update the docstring to reference the exported wrapper.The docstring still points callers to
getDarwinKit().icloud.onFilesChanged(handler), but the public API now exposesonIcloudFilesChanged()(lines 90-97). Update the comment to reference the wrapper instead.Suggested fix
/** * Start monitoring iCloud Drive for file changes. - * Use `getDarwinKit().icloud.onFilesChanged(handler)` to listen for changes. + * Use `onIcloudFilesChanged(handler)` to listen for changes. */
90-97: Well-designed subscription wrapper.The
onIcloudFilesChanged()wrapper correctly encapsulates the underlying client, accepts a handler, and returns the unsubscribe function. The JSDoc appropriately notes thaticloudStartMonitoring()must be called first..claude/plans/2026-03-12-DarwinKitCLI-design.md (2)
128-129: The piped stdin example does not match CLI implementation.The
detect-languagecommand requires thetextpositional argument. The current CLI implementation does not read from stdin when text is omitted, so this example will fail. Either update the example to pass text as an argument, or note this as a future enhancement.Suggested fix (update example)
# Piped -echo "Hello world" | tools darwinkit detect-language --format json | jq .language +tools darwinkit detect-language "Hello world" --format json | jq .language
1-134: Clear and well-structured design document.The architecture diagram, phased approach, and command groupings provide a solid foundation for the CLI implementation. The output format options and interactive flow behaviors are well-documented.
.claude/plans/2026-03-12-DarwinKitCLI.md (1)
1602-1615: Comprehensive verification checklist.The verification checklist covers TypeScript compilation, linting, tests, and manual smoke tests for both TTY and non-TTY scenarios. This ensures the implementation is thoroughly validated.
Comment on lines
+229
to
+243
| /** | ||
| * Start monitoring iCloud Drive for file changes. | ||
| * Use `getDarwinKit().icloud.onFilesChanged(handler)` to listen for changes. | ||
| */ | ||
| export async function icloudStartMonitoring(): Promise<ICloudOkResult> { | ||
| return getDarwinKit().icloud.startMonitoring(); | ||
| } | ||
|
|
||
| /** | ||
| * Stop monitoring iCloud Drive for file changes. | ||
| */ | ||
| export async function icloudStopMonitoring(): Promise<ICloudOkResult> { | ||
| return getDarwinKit().icloud.stopMonitoring(); | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Plan's icloud.ts snippet is missing the onIcloudFilesChanged wrapper.
The implementation plan's icloud.ts code (ending at line 243) does not include the onIcloudFilesChanged() subscription wrapper that was added in the actual implementation. Consider updating the plan to reflect the complete API surface.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/plans/2026-03-12-DarwinKitCLI.md around lines 229 - 243, The plan's
icloud.ts is missing the subscription wrapper present in the real
implementation: add an onIcloudFilesChanged function that exposes the underlying
subscription API by calling getDarwinKit().icloud.onFilesChanged(handler)
(matching the naming and semantics of the real implementation) so the plan
reflects the full API surface alongside the existing icloudStartMonitoring and
icloudStopMonitoring functions.
Comment on lines
+947
to
+1029
| // ── iCloud ─────────────────────────────────────────────────────────────── | ||
| { | ||
| name: "icloud-status", | ||
| group: "icloud", | ||
| description: "Check iCloud Drive availability and container URL", | ||
| params: [], | ||
| run: async () => icloudStatus(), | ||
| }, | ||
| { | ||
| name: "icloud-read", | ||
| group: "icloud", | ||
| description: "Read a text file from iCloud Drive", | ||
| params: [ | ||
| { name: "path", type: "string", required: true, positional: true, description: "File path in iCloud" }, | ||
| ], | ||
| run: async (args) => icloudRead(args.path as string), | ||
| }, | ||
| { | ||
| name: "icloud-write", | ||
| group: "icloud", | ||
| description: "Write text to a file in iCloud Drive", | ||
| params: [ | ||
| { name: "path", type: "string", required: true, positional: true, description: "File path in iCloud" }, | ||
| { name: "content", type: "string", required: true, description: "Content to write" }, | ||
| ], | ||
| run: async (args) => icloudWrite(args.path as string, args.content as string), | ||
| }, | ||
| { | ||
| name: "icloud-delete", | ||
| group: "icloud", | ||
| description: "Delete a file from iCloud Drive", | ||
| params: [ | ||
| { name: "path", type: "string", required: true, positional: true, description: "File path to delete" }, | ||
| ], | ||
| run: async (args) => icloudDelete(args.path as string), | ||
| }, | ||
| { | ||
| name: "icloud-move", | ||
| group: "icloud", | ||
| description: "Move/rename a file in iCloud Drive", | ||
| params: [ | ||
| { name: "source", type: "string", required: true, positional: true, description: "Source path" }, | ||
| { name: "destination", type: "string", required: true, positional: true, description: "Destination path" }, | ||
| ], | ||
| run: async (args) => icloudMove(args.source as string, args.destination as string), | ||
| }, | ||
| { | ||
| name: "icloud-copy", | ||
| group: "icloud", | ||
| description: "Copy a file in iCloud Drive", | ||
| params: [ | ||
| { name: "source", type: "string", required: true, positional: true, description: "Source path" }, | ||
| { name: "destination", type: "string", required: true, positional: true, description: "Destination path" }, | ||
| ], | ||
| run: async (args) => icloudCopy(args.source as string, args.destination as string), | ||
| }, | ||
| { | ||
| name: "icloud-list", | ||
| group: "icloud", | ||
| description: "List directory contents in iCloud Drive", | ||
| params: [ | ||
| { name: "path", type: "string", required: true, positional: true, description: "Directory path" }, | ||
| ], | ||
| run: async (args) => icloudList(args.path as string), | ||
| }, | ||
| { | ||
| name: "icloud-mkdir", | ||
| group: "icloud", | ||
| description: "Create a directory in iCloud Drive", | ||
| params: [ | ||
| { name: "path", type: "string", required: true, positional: true, description: "Directory path" }, | ||
| ], | ||
| run: async (args) => icloudMkdir(args.path as string), | ||
| }, | ||
|
|
||
| // ── System ─────────────────────────────────────────────────────────────── | ||
| { | ||
| name: "capabilities", | ||
| group: "system", | ||
| description: "Show DarwinKit version, OS, architecture, and available methods", | ||
| params: [], | ||
| run: async () => getCapabilities(), | ||
| }, |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Plan's iCloud command registry is incomplete.
The registry snippet in the plan omits icloud-write-bytes, icloud-start-monitoring, and icloud-stop-monitoring commands. These were added in the actual implementation per bcff54b. The plan document could be updated for completeness, but this is not blocking since the actual code is correct.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/plans/2026-03-12-DarwinKitCLI.md around lines 947 - 1029, The plan's
iCloud command registry is missing entries for the new commands added in
code—add registry entries for icloud-write-bytes, icloud-start-monitoring, and
icloud-stop-monitoring to match the implementation; include each command name,
group "icloud", a short description, appropriate params (e.g., path/bytes for
icloud-write-bytes and none for monitoring commands) and run handlers pointing
to icloudWriteBytes, icloudStartMonitoring, and icloudStopMonitoring
respectively so the plan and code stay in sync.
Comment on lines
+1127
to
+1170
| export async function runCommandInteractive( | ||
| cmd: CommandDef, | ||
| providedArgs: Record<string, unknown> = {} | ||
| ): Promise<void> { | ||
| // Show usage hint | ||
| const usage = buildUsageLine(cmd); | ||
| p.log.info(pc.dim(usage)); | ||
|
|
||
| // Prompt for missing required params | ||
| const args = { ...providedArgs }; | ||
|
|
||
| for (const param of cmd.params) { | ||
| if (args[param.name] !== undefined) { | ||
| continue; | ||
| } | ||
|
|
||
| if (!param.required && !process.stdout.isTTY) { | ||
| continue; | ||
| } | ||
|
|
||
| const value = await promptForParam(param); | ||
| if (value !== undefined) { | ||
| args[param.name] = value; | ||
| } | ||
| } | ||
|
|
||
| // Execute | ||
| const spin = p.spinner(); | ||
| spin.start(`Running ${cmd.name}...`); | ||
|
|
||
| try { | ||
| const result = await cmd.run(args); | ||
| spin.stop(`${cmd.name} complete`); | ||
|
|
||
| const format = defaultFormat(); | ||
| const output = formatOutput(result, format); | ||
| console.log(output); | ||
| } catch (error) { | ||
| spin.stop(pc.red(`${cmd.name} failed`)); | ||
| p.log.error(error instanceof Error ? error.message : String(error)); | ||
| } finally { | ||
| closeDarwinKit(); | ||
| } | ||
| } |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Plan's runCommandInteractive signature is stale.
The plan shows runCommandInteractive(cmd, providedArgs) without the formatOverride parameter that was added in the actual implementation (per bcff54b) to preserve the user's --format choice during interactive fallback. Consider updating the plan to match the implementation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/plans/2026-03-12-DarwinKitCLI.md around lines 1127 - 1170, Update
the stale runCommandInteractive signature to accept the new formatOverride
parameter and thread it through so the user's --format choice is preserved:
change the function signature for runCommandInteractive(cmd: CommandDef,
providedArgs: Record<string, unknown> = {}, formatOverride?: string) to include
formatOverride, keep prompting logic (promptForParam, buildUsageLine) unchanged,
then use format = defaultFormat(formatOverride) or otherwise pass formatOverride
into whatever defaultFormat/formatOutput call is used so the selected format is
honored when calling formatOutput(result, format), and update any call sites of
runCommandInteractive accordingly; ensure closeDarwinKit, spinner logic, and
error handling remain the same.
Comment on lines
+1466
to
+1469
| // Non-TTY: show help | ||
| sub.help(); | ||
| return; | ||
| } |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Plan uses sub.help() which causes TS7027 unreachable-code error.
Commander's Command.help() returns never (it calls process.exit internally), so the return statement after it is unreachable. The actual implementation should use sub.outputHelp() followed by process.exit(0). Based on learnings, this pattern was addressed in the actual code.
Suggested fix for plan
// Non-TTY: show help
- sub.help();
- return;
+ sub.outputHelp();
+ process.exit(1);
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/plans/2026-03-12-DarwinKitCLI.md around lines 1466 - 1469, Replace
the unreachable call pattern using sub.help() followed by return: Command.help()
is typed as never so the subsequent return triggers TS7027; update the non-TTY
branch to call sub.outputHelp() and then explicitly call process.exit(0) (i.e.,
replace sub.help() / return with sub.outputHelp(); process.exit(0)) so the
control flow and types are correct.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (2)
src/darwinkit/index.ts (2)
135-135:⚠️ Potential issue | 🟠 MajorRequired
string[]params can bypass validation with empty arrays.Line 135 only checks
undefined. For required list params normalized throughparseVariadic,[]should also be treated as missing; otherwise invalid invocations continue tocmd.run()with empty required input.💡 Proposed fix
- const missing = cmd.params.filter((pm) => pm.required && args[pm.name] === undefined); + const missing = cmd.params.filter((pm) => { + if (!pm.required) { + return false; + } + + const value = args[pm.name]; + return value === undefined || (Array.isArray(value) && value.length === 0); + });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/index.ts` at line 135, The required-parameter check in the cmd.params filter only treats undefined as missing, so variadic/list params normalized by parseVariadic (e.g., string[]) can pass validation as empty arrays; update the predicate used when computing missing (the filter that references cmd.params and args[pm.name]) to treat an empty array as missing too by checking: args[pm.name] === undefined OR (Array.isArray(args[pm.name]) && args[pm.name].length === 0); no other behavior changes needed—this will ensure required variadic params are rejected when they produce [] before reaching cmd.run().
145-146:⚠️ Potential issue | 🟠 MajorMissing required arguments should exit with a non-zero status.
Line 146 currently exits with
0, which signals success for an invalid invocation path.💡 Proposed fix
sub.outputHelp(); - process.exit(0); + process.exit(1);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/index.ts` around lines 145 - 146, The current branch that handles missing required arguments calls sub.outputHelp() then exits with success code 0; change this to exit with a non-zero status to signal failure (e.g., replace process.exit(0) with a non-zero exit or set process.exitCode = 1) in the block where sub.outputHelp() is called so the process returns a failure status when invocation is invalid.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/darwinkit/__tests__/cli-flags.test.ts`:
- Line 43: Remove the inline comments that simply restate adjacent
assertions—specifically delete the comment "Pretty format for objects should be
"key: value" lines, not JSON" and the two other adjacent comments referenced in
the same test case; leave the assertions and test logic (the expectations in the
cli-flags test) intact. Locate the comments in the cli-flags.test.ts test block
(the comment string above) and remove those comment lines so the test contains
only code and assertions, preserving existing assertion messages and behavior.
- Line 35: Replace the lenient SafeJSON.parse calls in the tests with strict
JSON parsing: locate the SafeJSON.parse(...) invocation(s) (e.g. the call that
assigns to the parsed variable) and remove the { unbox: true } option or use the
native JSON.parse(stdout) so the CLI output is validated against RFC‑compliant
JSON; update all occurrences noted (around the SafeJSON.parse call at the parsed
assignment and the similar calls at the other listed locations).
In `@src/darwinkit/__tests__/helpers.ts`:
- Line 32: The test helper currently parses subprocess output using
SafeJSON.parse(trimmed, { unbox: true }) which is lenient; change this call in
src/darwinkit/__tests__/helpers.ts (the function that returns SafeJSON.parse) to
use strict RFC‑8259 parsing by passing { strict: true } (e.g.,
SafeJSON.parse(trimmed, { strict: true, unbox: true })) so malformed CLI JSON
fails fast while preserving unboxing behavior.
In `@src/darwinkit/__tests__/vision.test.ts`:
- Around line 8-29: The Swift subprocess spawn in the beforeAll setup (the
Bun.spawn call that creates "proc" for image generation) currently ignores the
exit status; update the beforeAll to await proc.exited then check proc.exitCode
and if it's non-zero, read proc.stderr (and optionally proc.stdout) and throw or
fail with a clear error message including the exit code and stderr contents so
the test suite fails fast with meaningful diagnostics; reference the Bun.spawn
call that writes to "${TEST_IMAGE}" and ensure the check runs immediately after
awaiting proc.exited.
In `@src/utils/json.ts`:
- Around line 29-34: The ParseOptions.reviver case is not being recognized
because the options-detection in the SafeJSON.parse path only checks for
"jsonl", "strict", and "unbox", causing an object like { reviver } to be
misclassified as a legacy reviver; update the detection logic for
reviverOrOptions to include "reviver" (or explicitly check if
reviverOrOptions.reviver is present and is a function) so it gets cast to
ParseOptions, and ensure the fallback at the legacy-reviver handling (the code
around line handling of reviverOrOptions -> legacy reviver) still treats plain
functions as legacy revivers while typed objects with a reviver property are
handled as options (reference ParseOptions, reviverOrOptions, and
SafeJSON.parse).
---
Duplicate comments:
In `@src/darwinkit/index.ts`:
- Line 135: The required-parameter check in the cmd.params filter only treats
undefined as missing, so variadic/list params normalized by parseVariadic (e.g.,
string[]) can pass validation as empty arrays; update the predicate used when
computing missing (the filter that references cmd.params and args[pm.name]) to
treat an empty array as missing too by checking: args[pm.name] === undefined OR
(Array.isArray(args[pm.name]) && args[pm.name].length === 0); no other behavior
changes needed—this will ensure required variadic params are rejected when they
produce [] before reaching cmd.run().
- Around line 145-146: The current branch that handles missing required
arguments calls sub.outputHelp() then exits with success code 0; change this to
exit with a non-zero status to signal failure (e.g., replace process.exit(0)
with a non-zero exit or set process.exitCode = 1) in the block where
sub.outputHelp() is called so the process returns a failure status when
invocation is invalid.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: a11ee7da-6e2f-40ec-ac09-704a44378c7d
📒 Files selected for processing (12)
src/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/index.tssrc/utils/cli.tssrc/utils/json.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.ts: Usebun runto execute TypeScript files directly without a build step
Place general-purpose helper functions insrc/utils/instead of tool directories
Never add// src/path/to/file.tsas the first line of files
Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Always use block form with braces forifstatements, even for early returns; never use one-lineifstatements
Add an empty line beforeifstatements unless the preceding line is a variable declaration used by thatif
Add an empty line after closing}unless followed byelse,catch,finally, or another}
Noas anytype assertions; use proper type narrowing, type guards, or explicit interfaces instead
Use discriminant checks (e.g.,entity.className === "User") when working with union types instead of type assertions
Prefererror: errovererror: err instanceof Error ? err.message : String(err)when the error field accepts unknown type
Files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.ts: Use@clack/promptsfor interactive user prompts (preferred over@inquirer/prompts)
UseBun.spawn()for executing external commands and always check exit codes with meaningful error messages
Use Node.jspathmodule for cross-platform path handling and resolve relative paths to absolute usingresolve()
Use Bun's native file APIs (Bun.write()) for better performance instead of other file writing methods
Use centralized logging with pino logger outputting to/logs/directory organized by date
Handle user cancellation from prompts gracefully
Provide sensible defaults and suggestions in user prompts
Strip ANSI codes fromchalkcolored output for non-TTY environments
Files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
src/utils/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Check if a utility is general-purpose (usable by other tools) before deciding to place it in
src/utils/
Files:
src/utils/cli.tssrc/utils/json.ts
src/**/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/index.ts: Usecommanderfor parsing command-line arguments with subcommands and options
Support multiple output destinations (file, clipboard, stdout) and useclipboardyfor clipboard operations
Tool discovery checks for directories withindex.tsorindex.tsx(tool name = directory name) and standalone.tsor.tsxfiles (tool name = filename without extension)
Respect--silentand--verboseflags in tool output handling
Files:
src/darwinkit/index.ts
🧠 Learnings (37)
📓 Common learnings
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In the genesiscz/GenesisTools repo, Commander's `Command.help()` method is typed as `never` (it calls process.exit internally), so placing any statement after it (e.g., `return`) triggers TS7027 unreachable-code error. The idiomatic pattern for explicit, controlled exit in TypeScript is to use `sub.outputHelp()` (void-returning, just prints help) followed by `process.exit(0)` or `process.exit(1)`. Apply this pattern in all TypeScript files under src/ that use Commander subcommands and need to show help before exiting.
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In genesiscz/GenesisTools (src/**/*.ts), do not add inline comments for well-known POSIX patterns or standard idioms (e.g., process.kill(pid, 0) probe) when the surrounding code is already self-documenting via descriptive function/variable names. The project enforces a no-obvious-comments rule: avoid comments that merely restate what the code clearly expresses.
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Use `commander` for parsing command-line arguments with subcommands and options
Applied to files:
src/utils/cli.tssrc/darwinkit/index.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-02-20T00:52:27.023Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 31
File: src/ask/utils/helpers.ts:3-3
Timestamp: 2026-02-20T00:52:27.023Z
Learning: In all TypeScript source files under src, prefer using picocolors for colored terminal output in new code. Picocolors is smaller and faster than chalk, so adopt it for CLI output coloring and avoid adding chalk in new code paths unless there is a compelling compatibility reason.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-02-24T15:32:37.494Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/output.ts:109-113
Timestamp: 2026-02-24T15:32:37.494Z
Learning: In TypeScript files under src/, do not require a leading blank line before an if statement that is the first statement inside a function body (immediately after the function signature). The blank line rule should only apply to if statements that come after other statements within the function body. Apply this guideline consistently across TS files in src to reduce unnecessary vertical whitespace and keep concise function bodies.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-09T13:13:58.786Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:13:58.786Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), do not treat CI formatter warnings as enforceable formatting rules for TypeScript files under src/. Focus reviews on logical correctness and consistency with existing code patterns. For files under src (e.g., src/github/commands/get.ts), prioritize code structure, readability, naming, correctness, and adherence to project conventions over automated formatting warnings from CI tools.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:31.610Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/timely/utils/entry-processor.ts:0-0
Timestamp: 2026-03-12T01:26:31.610Z
Learning: In code paths where JSON is consumed, prefer strict RFC 8259 validation by using SafeJSON.parse(text, { strict: true }) instead of the lenient default. Apply this at non-config boundaries (e.g., API responses, JSONL, cache outputs, subprocess outputs). Reserve the lenient comment-json behavior only for user-authored config files that may legitimately contain comments or trailing commas. For src/timely/utils/entry-processor.ts and similar modules, replace or wrap JSON parsing with SafeJSON.parse(text, { strict: true }) unless you are explicitly handling config files that require comments.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In GenesisTools, apply a no-obvious-comments rule: do not add inline comments for well-known POSIX patterns or standard idioms (e.g., a process.kill(pid, 0) probe) when surrounding code is self-documenting through descriptive function/variable names. This guidance applies to TypeScript files under src (src/**/*.ts). Only include comments if they add non-obvious rationale, edge-case behavior, or explain complex logic that cannot be inferred from code alone.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-02-24T15:32:44.925Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:18-20
Timestamp: 2026-02-24T15:32:44.925Z
Learning: In TypeScript files, do not require a blank line between the opening brace of a function and the first statement if the first statement is the if statement immediately after the signature. The blank-line rule applies to separating an if from unrelated preceding code within the same block, not to spacing after the function opening brace. Apply this rule to all TS functions across the codebase.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation in all non-config boundaries (API responses, JSONL, cache, subprocess output). The 3-arg form SafeJSON.parse(text, null, { strict: true }) is invalid and should not be used. Only lenient default (no options) is appropriate for user-authored config files that may contain comments/trailing commas. Apply this guideline across TypeScript files (src/**/*.ts) wherever SafeJSON.parse is used.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:18.985Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/claude/lib/history/search.ts:0-0
Timestamp: 2026-03-12T01:26:18.985Z
Learning: When using SafeJSON.parse in TypeScript code, prefer the two-argument form SafeJSON.parse(text, { strict: true }) to enable strict RFC 8259 validation via the native JSON.parse. Do NOT use the three-argument form SafeJSON.parse(text, null, { strict: true }). Apply strict parsing at remote/third-party API boundaries, JSONL parsing points, and subprocess output. Fall back to the lenient/default form only for user-authored config files that may legitimately contain comments or trailing commas. This pattern keeps strict validation where appropriate and preserves leniency for internal/config data.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In the genesiscz/GenesisTools repository, prefer using SafeJSON.parse(text, { strict: true }) (2-argument form) at all non-config JSON boundaries such as API responses, JSONL parsers, cache files, and subprocess stdout. Reserve the lenient default (SafeJSON.parse(text) with no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In GenesisTools, ensure SafeJSON.parse is called with exactly two arguments. Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation, or pass a reviver function as the second argument. Do not call SafeJSON.parse(text, null, { strict: true }) since the function signature does not support a three-argument form. Apply this guideline to all TypeScript files that use SafeJSON.parse (e.g., src/utils/json.ts) and other related code.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T03:48:42.474Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In TypeScript files that use Commander subcommands and exit after showing help, replace code after Command.help() with the pattern: call sub.outputHelp(); (returns void) followed by process.exit(0) or process.exit(1). This avoids TS7027 unreachable-code because Command.help() returns never. Apply this pattern in all src/**/*.ts files where subcommands need to display help before exiting.
Applied to files:
src/utils/cli.tssrc/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/embeddings.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/classification.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/__tests__/icloud.test.tssrc/darwinkit/index.tssrc/utils/json.tssrc/darwinkit/__tests__/batch.test.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `Bun.spawn()` for executing external commands and always check exit codes with meaningful error messages
Applied to files:
src/darwinkit/__tests__/nlp.test.tssrc/darwinkit/__tests__/tts-auth-system.test.tssrc/darwinkit/__tests__/helpers.tssrc/darwinkit/__tests__/vision.test.tssrc/darwinkit/index.tssrc/darwinkit/__tests__/batch.test.ts
📚 Learning: 2026-03-15T15:49:04.626Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 106
File: plugins/genesis-tools/skills/github/scripts/actions-cost.ts:154-163
Timestamp: 2026-03-15T15:49:04.626Z
Learning: In genesiscz/GenesisTools, standalone bun scripts (e.g., `plugins/genesis-tools/skills/github/scripts/actions-cost.ts`) do not have access to `SafeJSON` from `app/utils/json`. When these scripts must use native `JSON.parse`, suppress the `noRestrictedGlobals` Biome rule with `// biome-ignore lint/style/noRestrictedGlobals: standalone script without access to SafeJSON` on the specific line, rather than importing SafeJSON.
Applied to files:
src/darwinkit/__tests__/helpers.ts
📚 Learning: 2026-03-15T15:53:59.249Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 105
File: src/ask/index.ts:66-74
Timestamp: 2026-03-15T15:53:59.249Z
Learning: In genesiscz/GenesisTools, manual argv._[0] dispatch in src/ask/index.ts (and similar entry-point files) is intentional for lazy loading: subcommand modules (e.g. ask/commands/configure) are imported via dynamic import() inside the dispatch branch rather than registered as Commander subcommands. This avoids eagerly loading all subcommand modules at startup. Do NOT flag this pattern as a violation of the "use Commander for subcommands" guideline; the lazy-loading benefit outweighs the missing Commander help/error-handling for these entry points.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:31.309Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/claude/auth.ts:0-0
Timestamp: 2026-03-12T01:26:31.309Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). There is no separate third `options` argument. Use `SafeJSON.parse(text, { strict: true })` at external/API/subprocess/JSONL/cache-file boundaries so malformed data fails fast with strict RFC 8259 validation. Use the lenient default (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/utils/json.ts
📚 Learning: 2026-02-24T15:39:24.751Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:182-210
Timestamp: 2026-02-24T15:39:24.751Z
Learning: In src/github/, output formatting uses separate functions for different modes: formatReviewTerminal() for colored terminal output, formatReviewMarkdown() for markdown files, and formatReviewJSON() for JSON. The caller selects the appropriate formatter based on output mode flags. Do not suggest adding TTY detection to individual formatters, as the architecture handles this through formatter separation.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:21.929Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/macos/lib/mail/jxa.ts:0-0
Timestamp: 2026-03-12T01:26:21.929Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. There is NO 3-argument overload — do NOT suggest `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at all remote/third-party API response boundaries, JSONL parsing points, subprocess stdout, and cache files; reserve lenient default (no second arg) only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:40.712Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/timelog/import.ts:0-0
Timestamp: 2026-03-12T01:26:40.712Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is overloaded: pass a function for a reviver, or pass `{ strict: true }` / `{ jsonl: true }` as a `ParseOptions` object to delegate to native `JSON.parse`. The correct strict-mode call is `SafeJSON.parse(text, { strict: true })` — NOT the 3-arg form `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output. Reserve the lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Handle user cancellation from prompts gracefully
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-11T17:12:19.730Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/clarity/ui/src/routes/settings.tsx:1-1
Timestamp: 2026-03-11T17:12:19.730Z
Learning: In genesiscz/GenesisTools, `SafeJSON` in `src/utils/json.ts` intentionally uses `comment-json.parse` for parsing (to handle `//` comments, trailing commas, unquoted keys) but `JSON.stringify` (native) for stringification. Do not flag `SafeJSON.stringify` usages as unnecessary — the intent is a unified drop-in for `JSON` that parses leniently but serialises as standard JSON.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In genesiscz/GenesisTools, enforce `SafeJSON.parse(text, { strict: true })` (2-arg form) at all non-config boundaries: API responses, JSONL lines, machine-generated cache files (e.g. `workitem-*.json`), and subprocess stdout. Reserve lenient/default parsing (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:10.028Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/cache.ts:0-0
Timestamp: 2026-03-12T01:26:10.028Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is a union of reviver function or options object. When `{ strict: true }` is passed as the second argument, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries, JSONL parsing points, machine-written cache files, and subprocess output that need strict RFC 8259 validation. The lenient default (no second arg or `null`) is only appropriate for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/utils/json.ts
📚 Learning: 2026-03-12T01:26:31.667Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/clarity/api.ts:0-0
Timestamp: 2026-03-12T01:26:31.667Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object (e.g. `{ strict: true }`). Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries (e.g. Clarity API, Timely API, Azure DevOps API) and JSONL/subprocess-output parsing points so malformed or non-standard responses fail fast. Fall back to the lenient default (no second arg, or `null`) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/utils/json.ts
📚 Learning: 2026-03-09T13:39:43.059Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-11T17:13:11.173Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/debugging-master/llm-log.ts:27-27
Timestamp: 2026-03-11T17:13:11.173Z
Learning: In genesiscz/GenesisTools, `src/utils/debugging-master/llm-log.ts` is intentionally self-contained with zero external dependencies (only Node.js builtins). Do not add imports from `app/utils/json` or any other internal module to this file. When native JSON methods must be used here, suppress the `noRestrictedGlobals` Biome rule with `// biome-ignore lint/style/noRestrictedGlobals: self-contained snippet with no external dependencies` on the specific line.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-15T16:03:26.354Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 106
File: plugins/genesis-tools/skills/github/scripts/actions-cost.ts:59-67
Timestamp: 2026-03-15T16:03:26.354Z
Learning: In `plugins/genesis-tools/skills/github/scripts/actions-cost.ts`, ubuntu-slim runner detection (1-core, $0.002/min) is intentionally omitted from `RUNNER_RATES` and `detectRunnerType`. The maintainer considers it rarely used in practice and has explicitly decided not to add detection for it. Do not flag its absence as an issue in future reviews.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:07.205Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/api.ts:0-0
Timestamp: 2026-03-12T01:26:07.205Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). When `{ strict: true }` is passed, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` (NOT the 3-arg form with `null`) at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output that need strict RFC 8259 validation. Fall back to lenient default (no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:34.357Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/workitem-precheck.ts:0-0
Timestamp: 2026-03-12T01:26:34.357Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is a union: either a reviver function or a ParseOptions object (`{ strict?: boolean, jsonl?: boolean, reviver?: Reviver }`). To use strict (native JSON.parse) mode at external API response boundaries, call `SafeJSON.parse(text, { strict: true })` — no `null` placeholder is needed. Lenient mode (default, uses comment-json) is only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:25.817Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/hold-ai/client.ts:0-0
Timestamp: 2026-03-12T01:26:25.817Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). To enable strict RFC 8259 validation (delegating to native `JSON.parse`), use `SafeJSON.parse(text, { strict: true })` — there is no separate third `options` parameter. Apply `{ strict: true }` at all non-config boundaries: API responses, JSONL parsing, cache files, and subprocess output. Reserve lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:18.251Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/core/session-manager.ts:172-175
Timestamp: 2026-03-12T01:26:18.251Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. Use this form at all non-config boundaries (API responses, JSONL lines, cache files, subprocess output). The lenient default (comment-json) should only be used for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:26.534Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/mcp-tsc/utils/ServerManager.ts:0-0
Timestamp: 2026-03-12T01:26:26.534Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly **two** arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is a union of a reviver function or a ParseOptions object — there is no separate third `options` argument. To enable strict RFC 8259 validation (native JSON.parse), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. Use this form at all external API response boundaries, JSONL parsing points, cache files, machine-written JSON files, and subprocess output. The lenient default (comment-json) is reserved for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:03.892Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/automate/lib/step-runner.ts:68-72
Timestamp: 2026-03-12T01:26:03.892Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is either a reviver function or an options object (e.g., `{ strict: true }`). To enforce strict RFC 8259 validation at remote/third-party API response boundaries, subprocess stdout, JSONL parsing, and cache files, use `SafeJSON.parse(text, { strict: true })`. Do NOT pass a null placeholder before the options object — the 3-arg form does not exist. The `JSON.parse` call inside the strict branch must be suppressed with `// biome-ignore lint/style/noRestrictedGlobals: intentional strict-mode fallback to native JSON.parse`.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:21.908Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/json/index.ts:0-0
Timestamp: 2026-03-12T01:26:21.908Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is a union type — pass a function for reviver behaviour, or pass `{ strict: true }` to delegate to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries, JSONL parsing points, and any conversion/validation tool (e.g. `src/json/index.ts`). The 3-arg form `SafeJSON.parse(text, null, { strict: true })` is incorrect — there is no third `options` parameter.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:05.589Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/automate/commands/task.ts:257-259
Timestamp: 2026-03-12T01:26:05.589Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is either a reviver function or an options object — not both simultaneously. To use strict mode (native JSON.parse), pass `SafeJSON.parse(text, { strict: true })`. There is NO 3-arg form. Use strict mode at all non-config boundaries: remote/third-party API responses, JSONL parsing points, cache files, subprocess stdout, and persisted DB state. Reserve lenient (default, no options) parsing only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Respect `--silent` and `--verbose` flags in tool output handling
Applied to files:
src/darwinkit/__tests__/cli-flags.test.ts
🧬 Code graph analysis (9)
src/darwinkit/__tests__/nlp.test.ts (1)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKit(11-33)
src/darwinkit/__tests__/embeddings.test.ts (1)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKit(11-33)
src/darwinkit/__tests__/tts-auth-system.test.ts (1)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKit(11-33)
src/darwinkit/__tests__/classification.test.ts (1)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKit(11-33)
src/darwinkit/__tests__/helpers.ts (1)
src/utils/json.ts (1)
SafeJSON(26-71)
src/darwinkit/__tests__/vision.test.ts (1)
src/darwinkit/__tests__/helpers.ts (2)
runDarwinKit(11-33)runDarwinKitRaw(38-52)
src/darwinkit/__tests__/icloud.test.ts (1)
src/darwinkit/__tests__/helpers.ts (2)
runDarwinKit(11-33)runDarwinKitRaw(38-52)
src/darwinkit/__tests__/batch.test.ts (1)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKit(11-33)
src/darwinkit/__tests__/cli-flags.test.ts (2)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKitRaw(38-52)src/utils/json.ts (1)
SafeJSON(26-71)
🔇 Additional comments (3)
src/darwinkit/__tests__/classification.test.ts (1)
4-86: Good coverage for classification command behaviors.The tests validate both multi-arg and comma-separated category inputs and assert the expected result structure without over-constraining model outcomes.
src/darwinkit/__tests__/embeddings.test.ts (1)
4-70: Embedding command tests look solid.Coverage includes key functional paths (vector shape, distance bounds, threshold behavior, and neighbors structure) and is aligned with CLI contract testing.
src/darwinkit/__tests__/batch.test.ts (1)
4-125: Comprehensive batch/text-analysis coverage.Nice job exercising shape expectations and comma-splitting across all major batch-style commands.
| it("json format outputs valid JSON", async () => { | ||
| const { stdout, exitCode } = await runDarwinKitRaw("sentiment", "Great!", "--format", "json"); | ||
| expect(exitCode).toBe(0); | ||
| const parsed = SafeJSON.parse(stdout, { unbox: true }); |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n src/darwinkit/__tests__/cli-flags.test.tsRepository: genesiscz/GenesisTools
Length of output: 4957
🏁 Script executed:
cat -n src/utils/json.tsRepository: genesiscz/GenesisTools
Length of output: 4111
Use strict JSON parsing for subprocess output validation.
These tests validate CLI --format json output, but SafeJSON.parse(..., { unbox: true }) uses lenient parsing and accepts non-RFC 8259 JSON, weakening the contract test's guarantee.
Suggested patch
- const parsed = SafeJSON.parse(stdout, { unbox: true });
+ const parsed = SafeJSON.parse(stdout, { strict: true });
@@
- const parsed = SafeJSON.parse(stdout, { unbox: true });
+ const parsed = SafeJSON.parse(stdout, { strict: true });
@@
- const parsed = SafeJSON.parse(stdout, { unbox: true });
+ const parsed = SafeJSON.parse(stdout, { strict: true });
@@
- const parsed = SafeJSON.parse(stdout, { unbox: true });
+ const parsed = SafeJSON.parse(stdout, { strict: true });Also applies to: 68-68, 83-83, 99-99
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/darwinkit/__tests__/cli-flags.test.ts` at line 35, Replace the lenient
SafeJSON.parse calls in the tests with strict JSON parsing: locate the
SafeJSON.parse(...) invocation(s) (e.g. the call that assigns to the parsed
variable) and remove the { unbox: true } option or use the native
JSON.parse(stdout) so the CLI output is validated against RFC‑compliant JSON;
update all occurrences noted (around the SafeJSON.parse call at the parsed
assignment and the similar calls at the other listed locations).
| throw new Error(`darwinkit ${args.join(" ")} produced no output`); | ||
| } | ||
|
|
||
| return SafeJSON.parse(trimmed, { unbox: true }); |
Contributor
There was a problem hiding this comment.
Use strict JSON parsing for subprocess output in test helpers.
Line 32 uses lenient parsing; this can mask malformed CLI JSON output. For subprocess boundaries, strict RFC 8259 parsing should fail fast.
💡 Proposed fix
- return SafeJSON.parse(trimmed, { unbox: true });
+ return SafeJSON.parse(trimmed, { strict: true });Based on learnings: use SafeJSON.parse(text, { strict: true }) at non-config boundaries (including subprocess output), and reserve lenient parsing for user-authored config files.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/darwinkit/__tests__/helpers.ts` at line 32, The test helper currently
parses subprocess output using SafeJSON.parse(trimmed, { unbox: true }) which is
lenient; change this call in src/darwinkit/__tests__/helpers.ts (the function
that returns SafeJSON.parse) to use strict RFC‑8259 parsing by passing { strict:
true } (e.g., SafeJSON.parse(trimmed, { strict: true, unbox: true })) so
malformed CLI JSON fails fast while preserving unboxing behavior.
genesiscz
added a commit
that referenced
this pull request
Mar 15, 2026
- Exit 1 (not 0) for missing required args in non-TTY mode - Validate --format before interactive fallback - Set process.exitCode=1 on interactive command failure - Treat empty string[] as missing in interactive prompts - Use comment-json's no_comments flag for unbox (no manual valueOf) - Add reviver to ParseOptions detection in SafeJSON.parse - Update icloud monitoring doc to reference exported wrapper - Stricter test assertions, remove redundant comments
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plugins/genesis-tools/hooks/track-session-files.ts (1)
85-85:⚠️ Potential issue | 🟠 MajorAdd biome-ignore suppression for
JSON.parseat line 85This line uses native
JSON.parsewithout suppression, causing anoRestrictedGlobalslint violation and CI failure. Add the biome-ignore comment directly above it, matching the pattern already used at lines 108, 114, and 120.Suggested fix
let sessionData: SessionData; if (existsSync(sessionFile)) { try { + // biome-ignore lint/style/noRestrictedGlobals: standalone hook script, no `@app/utils/json` available sessionData = JSON.parse(readFileSync(sessionFile, "utf-8")); } catch (_err) {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/genesis-tools/hooks/track-session-files.ts` at line 85, Add the biome-ignore suppression comment directly above the JSON.parse call that assigns sessionData (the line with sessionData = JSON.parse(readFileSync(sessionFile, "utf-8"));), using the same pattern as the existing suppressions (the biome-ignore for noRestrictedGlobals used elsewhere) so the linter ignores native JSON.parse at that location; ensure the comment is placed immediately on the line above the assignment.
♻️ Duplicate comments (2)
src/darwinkit/__tests__/cli-flags.test.ts (1)
35-35: 🧹 Nitpick | 🔵 TrivialConsider using strict JSON parsing for subprocess output validation.
These tests validate CLI
--format jsonoutput, butSafeJSON.parse(stdout, { unbox: true })uses lenient parsing that accepts non-RFC 8259 JSON. For contract tests, strict parsing would better validate that the CLI produces standards-compliant JSON.If unboxing is also needed, you could combine both concerns by first validating with native
JSON.parse, then using the result directly (no re-parsing needed):// Validates strict JSON compliance const parsed = JSON.parse(stdout); expect(parsed).toHaveProperty("label");Alternatively, if the
unboxbehavior is specifically required for test assertions, the current approach is acceptable—just be aware it won't catch non-compliant JSON output from the CLI.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/__tests__/cli-flags.test.ts` at line 35, The test currently uses SafeJSON.parse(stdout, { unbox: true }) which permits non-RFC-8259 JSON; replace it with strict parsing by using JSON.parse(stdout) to validate standards-compliant output (and then, if you still need the “unbox” behavior for assertions, use the parsed value directly instead of re-parsing with SafeJSON). Specifically, change the call to SafeJSON.parse in the test to const parsed = JSON.parse(stdout); and then use parsed (or extract the unboxed value from parsed) in subsequent expects to ensure strict JSON validation of the CLI output.src/darwinkit/lib/interactive.ts (1)
134-151:⚠️ Potential issue | 🟡 MinorEmpty
string[]input returns empty array instead of respecting default.The past review suggested that when the user enters an empty string for a
string[]parameter with a default value, the default should be returned instead of an empty array. Currently, empty input always returns[](line 144), which ignoresparam.default.💡 Suggested fix to respect defaults
const str = (result as string).trim(); if (str === "") { - return []; + return param.default ?? []; } return str🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/darwinkit/lib/interactive.ts` around lines 134 - 151, The prompt handler for params of type "string[]" currently returns [] on empty input, ignoring param.default; update the empty-input branch in the withCancel/p.text handler so that when str === "" you return the default value if provided: if param.default is an array, return it; if it's a string, split it by commas and trim/filter to produce a string[]; otherwise return []—make this change near the "if (param.type === \"string[]\")" block around the withCancel/p.text result handling to ensure defaults are respected.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/genesis-tools/hooks/track-session-files.ts`:
- Around line 120-122: The biome suppression comment for
lint/style/noRestrictedGlobals must be moved to sit immediately above the
JSON.stringify call so it targets that exact statement; update the snippet that
uses console.log(JSON.stringify(...)) by placing the comment "// biome-ignore
lint/style/noRestrictedGlobals: standalone hook script, no `@app/utils/json`
available" directly on the line before the JSON.stringify invocation (i.e.,
immediately above JSON.stringify) so the linter suppression applies to the
JSON.stringify call.
In `@src/utils/macos/icloud.ts`:
- Around line 39-41: Remove the trivial JSDoc blocks that merely restate the
exported wrapper names for the simple pass-through functions (the exported
functions named delete, copy, list and stopMonitoring in this module); delete
those boilerplate comments (lines currently summarizing "Delete a file from
iCloud Drive.", similar summaries at 53-55, 60-62, 83-85) and only keep or
expand JSDoc where it conveys actual contract/usage details (parameters, return
value, errors) for the corresponding function implementations.
---
Outside diff comments:
In `@plugins/genesis-tools/hooks/track-session-files.ts`:
- Line 85: Add the biome-ignore suppression comment directly above the
JSON.parse call that assigns sessionData (the line with sessionData =
JSON.parse(readFileSync(sessionFile, "utf-8"));), using the same pattern as the
existing suppressions (the biome-ignore for noRestrictedGlobals used elsewhere)
so the linter ignores native JSON.parse at that location; ensure the comment is
placed immediately on the line above the assignment.
---
Duplicate comments:
In `@src/darwinkit/__tests__/cli-flags.test.ts`:
- Line 35: The test currently uses SafeJSON.parse(stdout, { unbox: true }) which
permits non-RFC-8259 JSON; replace it with strict parsing by using
JSON.parse(stdout) to validate standards-compliant output (and then, if you
still need the “unbox” behavior for assertions, use the parsed value directly
instead of re-parsing with SafeJSON). Specifically, change the call to
SafeJSON.parse in the test to const parsed = JSON.parse(stdout); and then use
parsed (or extract the unboxed value from parsed) in subsequent expects to
ensure strict JSON validation of the CLI output.
In `@src/darwinkit/lib/interactive.ts`:
- Around line 134-151: The prompt handler for params of type "string[]"
currently returns [] on empty input, ignoring param.default; update the
empty-input branch in the withCancel/p.text handler so that when str === "" you
return the default value if provided: if param.default is an array, return it;
if it's a string, split it by commas and trim/filter to produce a string[];
otherwise return []—make this change near the "if (param.type === \"string[]\")"
block around the withCancel/p.text result handling to ensure defaults are
respected.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 69b60947-caa1-460a-ab4d-f3b902c1cca9
📒 Files selected for processing (7)
plugins/genesis-tools/hooks/track-session-files.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.ts: Usebun runto execute TypeScript files directly without a build step
Place general-purpose helper functions insrc/utils/instead of tool directories
Never add// src/path/to/file.tsas the first line of files
Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Always use block form with braces forifstatements, even for early returns; never use one-lineifstatements
Add an empty line beforeifstatements unless the preceding line is a variable declaration used by thatif
Add an empty line after closing}unless followed byelse,catch,finally, or another}
Noas anytype assertions; use proper type narrowing, type guards, or explicit interfaces instead
Use discriminant checks (e.g.,entity.className === "User") when working with union types instead of type assertions
Prefererror: errovererror: err instanceof Error ? err.message : String(err)when the error field accepts unknown type
Files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
src/**/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/index.ts: Usecommanderfor parsing command-line arguments with subcommands and options
Support multiple output destinations (file, clipboard, stdout) and useclipboardyfor clipboard operations
Tool discovery checks for directories withindex.tsorindex.tsx(tool name = directory name) and standalone.tsor.tsxfiles (tool name = filename without extension)
Respect--silentand--verboseflags in tool output handling
Files:
src/darwinkit/index.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.ts: Use@clack/promptsfor interactive user prompts (preferred over@inquirer/prompts)
UseBun.spawn()for executing external commands and always check exit codes with meaningful error messages
Use Node.jspathmodule for cross-platform path handling and resolve relative paths to absolute usingresolve()
Use Bun's native file APIs (Bun.write()) for better performance instead of other file writing methods
Use centralized logging with pino logger outputting to/logs/directory organized by date
Handle user cancellation from prompts gracefully
Provide sensible defaults and suggestions in user prompts
Strip ANSI codes fromchalkcolored output for non-TTY environments
Files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
src/utils/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Check if a utility is general-purpose (usable by other tools) before deciding to place it in
src/utils/
Files:
src/utils/json.tssrc/utils/macos/icloud.ts
🧠 Learnings (49)
📓 Common learnings
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In genesiscz/GenesisTools (src/**/*.ts), do not add inline comments for well-known POSIX patterns or standard idioms (e.g., process.kill(pid, 0) probe) when the surrounding code is already self-documenting via descriptive function/variable names. The project enforces a no-obvious-comments rule: avoid comments that merely restate what the code clearly expresses.
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Use `commander` for parsing command-line arguments with subcommands and options
Applied to files:
src/darwinkit/index.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-15T15:53:59.249Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 105
File: src/ask/index.ts:66-74
Timestamp: 2026-03-15T15:53:59.249Z
Learning: In genesiscz/GenesisTools, manual argv._[0] dispatch in src/ask/index.ts (and similar entry-point files) is intentional for lazy loading: subcommand modules (e.g. ask/commands/configure) are imported via dynamic import() inside the dispatch branch rather than registered as Commander subcommands. This avoids eagerly loading all subcommand modules at startup. Do NOT flag this pattern as a violation of the "use Commander for subcommands" guideline; the lazy-loading benefit outweighs the missing Commander help/error-handling for these entry points.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T03:48:42.474Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 104
File: src/darwinkit/index.ts:146-156
Timestamp: 2026-03-12T03:48:42.474Z
Learning: In TypeScript files that use Commander subcommands and exit after showing help, replace code after Command.help() with the pattern: call sub.outputHelp(); (returns void) followed by process.exit(0) or process.exit(1). This avoids TS7027 unreachable-code because Command.help() returns never. Apply this pattern in all src/**/*.ts files where subcommands need to display help before exiting.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:03.611Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/ask/lib/ChatSessionManager.ts:0-0
Timestamp: 2026-03-12T01:26:03.611Z
Learning: Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation in all non-config boundaries (API responses, JSONL, cache, subprocess output). The 3-arg form SafeJSON.parse(text, null, { strict: true }) is invalid and should not be used. Only lenient default (no options) is appropriate for user-authored config files that may contain comments/trailing commas. Apply this guideline across TypeScript files (src/**/*.ts) wherever SafeJSON.parse is used.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:31.309Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/claude/auth.ts:0-0
Timestamp: 2026-03-12T01:26:31.309Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). There is no separate third `options` argument. Use `SafeJSON.parse(text, { strict: true })` at external/API/subprocess/JSONL/cache-file boundaries so malformed data fails fast with strict RFC 8259 validation. Use the lenient default (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.ts
📚 Learning: 2026-02-24T15:39:24.751Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:182-210
Timestamp: 2026-02-24T15:39:24.751Z
Learning: In src/github/, output formatting uses separate functions for different modes: formatReviewTerminal() for colored terminal output, formatReviewMarkdown() for markdown files, and formatReviewJSON() for JSON. The caller selects the appropriate formatter based on output mode flags. Do not suggest adding TTY detection to individual formatters, as the architecture handles this through formatter separation.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-03-12T01:26:21.929Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/macos/lib/mail/jxa.ts:0-0
Timestamp: 2026-03-12T01:26:21.929Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. There is NO 3-argument overload — do NOT suggest `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at all remote/third-party API response boundaries, JSONL parsing points, subprocess stdout, and cache files; reserve lenient default (no second arg) only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.ts
📚 Learning: 2026-03-12T01:26:40.712Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/timelog/import.ts:0-0
Timestamp: 2026-03-12T01:26:40.712Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is overloaded: pass a function for a reviver, or pass `{ strict: true }` / `{ jsonl: true }` as a `ParseOptions` object to delegate to native `JSON.parse`. The correct strict-mode call is `SafeJSON.parse(text, { strict: true })` — NOT the 3-arg form `SafeJSON.parse(text, null, { strict: true })`. Use strict mode at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output. Reserve the lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-09T13:13:58.786Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:13:58.786Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), do not treat CI formatter warnings as enforceable formatting rules for TypeScript files under src/. Focus reviews on logical correctness and consistency with existing code patterns. For files under src (e.g., src/github/commands/get.ts), prioritize code structure, readability, naming, correctness, and adherence to project conventions over automated formatting warnings from CI tools.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `Bun.spawn()` for executing external commands and always check exit codes with meaningful error messages
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Handle user cancellation from prompts gracefully
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In GenesisTools, apply a no-obvious-comments rule: do not add inline comments for well-known POSIX patterns or standard idioms (e.g., a process.kill(pid, 0) probe) when surrounding code is self-documenting through descriptive function/variable names. This guidance applies to TypeScript files under src (src/**/*.ts). Only include comments if they add non-obvious rationale, edge-case behavior, or explain complex logic that cannot be inferred from code alone.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-11T17:12:19.730Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/clarity/ui/src/routes/settings.tsx:1-1
Timestamp: 2026-03-11T17:12:19.730Z
Learning: In genesiscz/GenesisTools, `SafeJSON` in `src/utils/json.ts` intentionally uses `comment-json.parse` for parsing (to handle `//` comments, trailing commas, unquoted keys) but `JSON.stringify` (native) for stringification. Do not flag `SafeJSON.stringify` usages as unnecessary — the intent is a unified drop-in for `JSON` that parses leniently but serialises as standard JSON.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In genesiscz/GenesisTools, enforce `SafeJSON.parse(text, { strict: true })` (2-arg form) at all non-config boundaries: API responses, JSONL lines, machine-generated cache files (e.g. `workitem-*.json`), and subprocess stdout. Reserve lenient/default parsing (no second arg) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:10.028Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/cache.ts:0-0
Timestamp: 2026-03-12T01:26:10.028Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is a union of reviver function or options object. When `{ strict: true }` is passed as the second argument, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries, JSONL parsing points, machine-written cache files, and subprocess output that need strict RFC 8259 validation. The lenient default (no second arg or `null`) is only appropriate for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.ts
📚 Learning: 2026-03-12T01:26:31.667Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/clarity/api.ts:0-0
Timestamp: 2026-03-12T01:26:31.667Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object (e.g. `{ strict: true }`). Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries (e.g. Clarity API, Timely API, Azure DevOps API) and JSONL/subprocess-output parsing points so malformed or non-standard responses fail fast. Fall back to the lenient default (no second arg, or `null`) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/telegram/lib/actions/ask.tssrc/utils/json.ts
📚 Learning: 2026-03-09T13:39:43.059Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 82
File: src/claude/lib/usage/dashboard-config.ts:24-25
Timestamp: 2026-03-09T13:39:43.059Z
Learning: GenesisTools (genesiscz/GenesisTools) is a personal CLI tool, not a multi-tenant service. Do not suggest data migration paths or backward-compatibility shims for simple default value changes in configuration files (e.g., dashboard-config.ts). The TUI provides interactive controls (e.g., the `i` key to cycle poll intervals at runtime), so users can adjust settings without needing automated migrations. Avoid overengineering suggestions in this context.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.ts
📚 Learning: 2026-03-11T17:13:11.173Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/utils/debugging-master/llm-log.ts:27-27
Timestamp: 2026-03-11T17:13:11.173Z
Learning: In genesiscz/GenesisTools, `src/utils/debugging-master/llm-log.ts` is intentionally self-contained with zero external dependencies (only Node.js builtins). Do not add imports from `app/utils/json` or any other internal module to this file. When native JSON methods must be used here, suppress the `noRestrictedGlobals` Biome rule with `// biome-ignore lint/style/noRestrictedGlobals: self-contained snippet with no external dependencies` on the specific line.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-15T16:03:26.354Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 106
File: plugins/genesis-tools/skills/github/scripts/actions-cost.ts:59-67
Timestamp: 2026-03-15T16:03:26.354Z
Learning: In `plugins/genesis-tools/skills/github/scripts/actions-cost.ts`, ubuntu-slim runner detection (1-core, $0.002/min) is intentionally omitted from `RUNNER_RATES` and `detectRunnerType`. The maintainer considers it rarely used in practice and has explicitly decided not to add detection for it. Do not flag its absence as an issue in future reviews.
Applied to files:
src/darwinkit/index.ts
📚 Learning: 2026-02-20T00:52:27.023Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 31
File: src/ask/utils/helpers.ts:3-3
Timestamp: 2026-02-20T00:52:27.023Z
Learning: In all TypeScript source files under src, prefer using picocolors for colored terminal output in new code. Picocolors is smaller and faster than chalk, so adopt it for CLI output coloring and avoid adding chalk in new code paths unless there is a compelling compatibility reason.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-24T15:32:37.494Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/output.ts:109-113
Timestamp: 2026-02-24T15:32:37.494Z
Learning: In TypeScript files under src/, do not require a leading blank line before an if statement that is the first statement inside a function body (immediately after the function signature). The blank line rule should only apply to if statements that come after other statements within the function body. Apply this guideline consistently across TS files in src to reduce unnecessary vertical whitespace and keep concise function bodies.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:31.610Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/timely/utils/entry-processor.ts:0-0
Timestamp: 2026-03-12T01:26:31.610Z
Learning: In code paths where JSON is consumed, prefer strict RFC 8259 validation by using SafeJSON.parse(text, { strict: true }) instead of the lenient default. Apply this at non-config boundaries (e.g., API responses, JSONL, cache outputs, subprocess outputs). Reserve the lenient comment-json behavior only for user-authored config files that may legitimately contain comments or trailing commas. For src/timely/utils/entry-processor.ts and similar modules, replace or wrap JSON parsing with SafeJSON.parse(text, { strict: true }) unless you are explicitly handling config files that require comments.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-24T15:32:44.925Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/github/lib/review-output.ts:18-20
Timestamp: 2026-02-24T15:32:44.925Z
Learning: In TypeScript files, do not require a blank line between the opening brace of a function and the first statement if the first statement is the if statement immediately after the signature. The blank-line rule applies to separating an if from unrelated preceding code within the same block, not to spacing after the function opening brace. Apply this rule to all TS functions across the codebase.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:18.985Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/claude/lib/history/search.ts:0-0
Timestamp: 2026-03-12T01:26:18.985Z
Learning: When using SafeJSON.parse in TypeScript code, prefer the two-argument form SafeJSON.parse(text, { strict: true }) to enable strict RFC 8259 validation via the native JSON.parse. Do NOT use the three-argument form SafeJSON.parse(text, null, { strict: true }). Apply strict parsing at remote/third-party API boundaries, JSONL parsing points, and subprocess output. Fall back to the lenient/default form only for user-authored config files that may legitimately contain comments or trailing commas. This pattern keeps strict validation where appropriate and preserves leniency for internal/config data.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:27.000Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/commands/tail.ts:0-0
Timestamp: 2026-03-12T01:26:27.000Z
Learning: In the genesiscz/GenesisTools repository, prefer using SafeJSON.parse(text, { strict: true }) (2-argument form) at all non-config JSON boundaries such as API responses, JSONL parsers, cache files, and subprocess stdout. Reserve the lenient default (SafeJSON.parse(text) with no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-12T01:26:24.859Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/history-sync.ts:0-0
Timestamp: 2026-03-12T01:26:24.859Z
Learning: In GenesisTools, ensure SafeJSON.parse is called with exactly two arguments. Use SafeJSON.parse(text, { strict: true }) for strict RFC 8259 validation, or pass a reviver function as the second argument. Do not call SafeJSON.parse(text, null, { strict: true }) since the function signature does not support a three-argument form. Apply this guideline to all TypeScript files that use SafeJSON.parse (e.g., src/utils/json.ts) and other related code.
Applied to files:
src/darwinkit/index.tssrc/darwinkit/lib/interactive.tsplugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Use `clack/prompts` for interactive user prompts (preferred over `inquirer/prompts`)
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-03-08T23:00:34.621Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 78
File: .claude/github/reviews/pr-74-2026-03-03T02-02-09.md:0-0
Timestamp: 2026-03-08T23:00:34.621Z
Learning: In the GenesisTools repository, files under the `.claude/github/reviews/` directory (e.g., `.claude/github/reviews/pr-74-2026-03-03T02-02-09.md`) are PR review artifacts that should NOT be committed to the repository. Flag any such files appearing in a PR diff as unrelated stray artifacts that should be removed from the branch/commit.
Applied to files:
src/darwinkit/lib/interactive.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/*.ts : Provide sensible defaults and suggestions in user prompts
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: The `tools` executable shows an interactive tool selector using inquirer/prompts when run without arguments
Applied to files:
src/darwinkit/lib/interactive.ts
📚 Learning: 2026-03-12T01:58:27.831Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 103
File: src/port/index.ts:137-144
Timestamp: 2026-03-12T01:58:27.831Z
Learning: In genesiscz/GenesisTools (src/**/*.ts), do not add inline comments for well-known POSIX patterns or standard idioms (e.g., process.kill(pid, 0) probe) when the surrounding code is already self-documenting via descriptive function/variable names. The project enforces a no-obvious-comments rule: avoid comments that merely restate what the code clearly expresses.
Applied to files:
plugins/genesis-tools/hooks/track-session-files.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to **/*.ts : Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)
Applied to files:
plugins/genesis-tools/hooks/track-session-files.tssrc/darwinkit/__tests__/cli-flags.test.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-09T13:14:03.722Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 81
File: src/github/commands/get.ts:209-212
Timestamp: 2026-03-09T13:14:03.722Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), there is no CI formatter (e.g., Prettier/Biome) configured or enforced. Do not flag formatting mismatches based on static analysis tool annotations (e.g., GitHub Actions CI formatter warnings) in this repository, as they are not representative of actual enforced formatting rules. TypeScript files under src/ should be reviewed for logical correctness and consistency with existing code patterns instead.
Applied to files:
plugins/genesis-tools/hooks/track-session-files.ts
📚 Learning: 2026-03-15T15:49:04.626Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 106
File: plugins/genesis-tools/skills/github/scripts/actions-cost.ts:154-163
Timestamp: 2026-03-15T15:49:04.626Z
Learning: In genesiscz/GenesisTools, standalone bun scripts (e.g., `plugins/genesis-tools/skills/github/scripts/actions-cost.ts`) do not have access to `SafeJSON` from `app/utils/json`. When these scripts must use native `JSON.parse`, suppress the `noRestrictedGlobals` Biome rule with `// biome-ignore lint/style/noRestrictedGlobals: standalone script without access to SafeJSON` on the specific line, rather than importing SafeJSON.
Applied to files:
plugins/genesis-tools/hooks/track-session-files.tssrc/telegram/lib/actions/ask.ts
📚 Learning: 2026-03-11T14:37:42.310Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 87
File: docs/typescript-sdks/apple/github-repos-index.md:94-94
Timestamp: 2026-03-11T14:37:42.310Z
Learning: In the GenesisTools repo (genesiscz/GenesisTools), docs under `docs/typescript-sdks/apple/` (e.g., `github-repos-index.md`, `macos-node-api.md`) are auto-generated. Do not flag trivial markdown formatting issues (e.g., MD022 blank lines around headings, MD031, etc.) in these files, as they will not be manually fixed.
Applied to files:
plugins/genesis-tools/hooks/track-session-files.tssrc/utils/macos/icloud.ts
📚 Learning: 2026-03-15T16:03:42.969Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 106
File: plugins/genesis-tools/skills/github/scripts/actions-cost.ts:9-12
Timestamp: 2026-03-15T16:03:42.969Z
Learning: In genesiscz/GenesisTools, for standalone bun scripts under plugins/genesis-tools (e.g., plugins/genesis-tools/skills/github/scripts/actions-cost.ts), use the invocation bun file.ts, not bun run file.ts. Bun run is reserved for package.json script entries. The shebang #!/usr/bin/env bun marks such scripts as standalone. Do not suggest replacing bun file.ts with bun run file.ts in usage/help text for standalone scripts.
Applied to files:
plugins/genesis-tools/hooks/track-session-files.ts
📚 Learning: 2026-03-12T01:26:21.361Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/daemon/lib/log-reader.ts:0-0
Timestamp: 2026-03-12T01:26:21.361Z
Learning: In genesiscz/GenesisTools, enforce SafeJSON.parse strict mode at all non-config boundaries: external API responses, JSONL line parsers, cache files, and subprocess stdout. Use `SafeJSON.parse(input, { strict: true })` (2-arg form). Fall back to lenient default (no second arg) only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/telegram/lib/actions/ask.tssrc/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:21.908Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/json/index.ts:0-0
Timestamp: 2026-03-12T01:26:21.908Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is a union type — pass a function for reviver behaviour, or pass `{ strict: true }` to delegate to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` at remote/third-party API response boundaries, JSONL parsing points, and any conversion/validation tool (e.g. `src/json/index.ts`). The 3-arg form `SafeJSON.parse(text, null, { strict: true })` is incorrect — there is no third `options` parameter.
Applied to files:
src/telegram/lib/actions/ask.tssrc/utils/json.ts
📚 Learning: 2026-02-20T01:35:08.233Z
Learnt from: CR
Repo: genesiscz/GenesisTools PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T01:35:08.233Z
Learning: Applies to src/**/index.ts : Respect `--silent` and `--verbose` flags in tool output handling
Applied to files:
src/darwinkit/__tests__/cli-flags.test.ts
📚 Learning: 2026-03-12T01:26:07.205Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/api.ts:0-0
Timestamp: 2026-03-12T01:26:07.205Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). When `{ strict: true }` is passed, it delegates to native `JSON.parse` instead of `comment-json`'s lenient parser. Use `SafeJSON.parse(text, { strict: true })` (NOT the 3-arg form with `null`) at remote/third-party API response boundaries, JSONL parsing points, cache files, and subprocess output that need strict RFC 8259 validation. Fall back to lenient default (no options) only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/darwinkit/__tests__/cli-flags.test.tssrc/utils/json.ts
📚 Learning: 2026-03-12T01:26:34.357Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/workitem-precheck.ts:0-0
Timestamp: 2026-03-12T01:26:34.357Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is a union: either a reviver function or a ParseOptions object (`{ strict?: boolean, jsonl?: boolean, reviver?: Reviver }`). To use strict (native JSON.parse) mode at external API response boundaries, call `SafeJSON.parse(text, { strict: true })` — no `null` placeholder is needed. Lenient mode (default, uses comment-json) is only for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:18.251Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/debugging-master/core/session-manager.ts:172-175
Timestamp: 2026-03-12T01:26:18.251Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or an options object. To enable strict RFC 8259 validation (delegating to native `JSON.parse`), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. Use this form at all non-config boundaries (API responses, JSONL lines, cache files, subprocess output). The lenient default (comment-json) should only be used for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:03.892Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/automate/lib/step-runner.ts:68-72
Timestamp: 2026-03-12T01:26:03.892Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second parameter is either a reviver function or an options object (e.g., `{ strict: true }`). To enforce strict RFC 8259 validation at remote/third-party API response boundaries, subprocess stdout, JSONL parsing, and cache files, use `SafeJSON.parse(text, { strict: true })`. Do NOT pass a null placeholder before the options object — the 3-arg form does not exist. The `JSON.parse` call inside the strict branch must be suppressed with `// biome-ignore lint/style/noRestrictedGlobals: intentional strict-mode fallback to native JSON.parse`.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:25.817Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/hold-ai/client.ts:0-0
Timestamp: 2026-03-12T01:26:25.817Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument can be either a reviver function or a `ParseOptions` object (e.g., `{ strict: true }`). To enable strict RFC 8259 validation (delegating to native `JSON.parse`), use `SafeJSON.parse(text, { strict: true })` — there is no separate third `options` parameter. Apply `{ strict: true }` at all non-config boundaries: API responses, JSONL parsing, cache files, and subprocess output. Reserve lenient default (no options) for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:26.534Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/mcp-tsc/utils/ServerManager.ts:0-0
Timestamp: 2026-03-12T01:26:26.534Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts exactly **two** arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is a union of a reviver function or a ParseOptions object — there is no separate third `options` argument. To enable strict RFC 8259 validation (native JSON.parse), pass `{ strict: true }` as the second argument: `SafeJSON.parse(text, { strict: true })`. Use this form at all external API response boundaries, JSONL parsing points, cache files, machine-written JSON files, and subprocess output. The lenient default (comment-json) is reserved for user-authored config files that may contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:19.243Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/azure-devops/commands/timelog/configure.ts:0-0
Timestamp: 2026-03-12T01:26:19.243Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts two arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is a union type — pass a function for a reviver, or a `ParseOptions` object for options. To enforce strict RFC 8259 validation at remote/third-party API response boundaries, use `SafeJSON.parse(text, { strict: true })` (2-arg form). Do NOT pass `null` as a second arg before the options object — there is no separate third `options` parameter.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-03-12T01:26:05.589Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 95
File: src/automate/commands/task.ts:257-259
Timestamp: 2026-03-12T01:26:05.589Z
Learning: In genesiscz/GenesisTools, `SafeJSON.parse` in `src/utils/json.ts` accepts TWO arguments: `(text: string, reviverOrOptions?: Reviver | ParseOptions | null)`. The second argument is either a reviver function or an options object — not both simultaneously. To use strict mode (native JSON.parse), pass `SafeJSON.parse(text, { strict: true })`. There is NO 3-arg form. Use strict mode at all non-config boundaries: remote/third-party API responses, JSONL parsing points, cache files, subprocess stdout, and persisted DB state. Reserve lenient (default, no options) parsing only for user-authored config files that may legitimately contain comments or trailing commas.
Applied to files:
src/utils/json.ts
📚 Learning: 2026-02-24T22:38:46.781Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 54
File: src/watchman/index.ts:98-99
Timestamp: 2026-02-24T22:38:46.781Z
Learning: In src/watchman/index.ts, `as any` casts are necessary when calling fb-watchman Client methods (e.g., `client.command()`, `client.on("subscription", ...)`) because types/fb-watchman has incomplete type definitions. Using the local WatchmanResponse interface causes TS2769 errors. The biome-ignore comments document this justified exception to the general no-any guideline.
Applied to files:
src/utils/macos/icloud.ts
🧬 Code graph analysis (2)
src/telegram/lib/actions/ask.ts (1)
src/utils/json.ts (1)
SafeJSON(26-63)
src/darwinkit/__tests__/cli-flags.test.ts (2)
src/darwinkit/__tests__/helpers.ts (1)
runDarwinKitRaw(38-52)src/utils/json.ts (1)
SafeJSON(26-63)
🪛 GitHub Actions: CI
plugins/genesis-tools/hooks/track-session-files.ts
[error] 120-120: Suppression comment has no effect. Remove the suppression or apply the correct rule.
[error] 85-85: lint/style/noRestrictedGlobals: Do not use the global variable JSON.
[error] 122-122: lint/style/noRestrictedGlobals: Do not use the global variable JSON.
src/utils/json.ts
[error] 30-35: Formatter would have printed different content. Run the formatter to fix formatting issues in this file.
🔇 Additional comments (11)
src/utils/json.ts (1)
29-45: Fix formatter issue flagged by CI.The pipeline reports a formatting issue on lines 30-35. Run the formatter to resolve this before merging.
The logic changes look correct:
- Detection now properly includes all
ParseOptionskeys (jsonl,strict,unbox,reviver).- The
unboxoption correctly passes tocomment-json's third argument.- Legacy reviver handling now safely checks
typeof reviverOrOptions === "function"before using it.src/telegram/lib/actions/ask.ts (1)
4-4: LGTM!The migration to
SafeJSON.stringifyfor logging is consistent with the codebase's unified JSON handling approach. SinceSafeJSON.stringifydelegates to nativeJSON.stringifyfor standard serialization, this maintains correctness while aligning with project conventions.Also applies to: 58-58, 65-65
src/darwinkit/__tests__/cli-flags.test.ts (2)
5-53: LGTM!The help, version, and format tests are well-structured with clear assertions. Exit code validation ensures proper CLI behavior, and the format tests appropriately distinguish between JSON, pretty, and raw outputs.
55-99: LGTM!Good coverage for comma-separated array parameter parsing. The tests verify that
--items,--schemes, and--categoriescorrectly split comma-separated values into arrays.src/darwinkit/lib/interactive.ts (3)
1-94: LGTM!Clean implementation of the interactive flow:
runInteractiveMenuproperly filters groups with commands and uses descriptive hints.runCommandInteractivecorrectly shows usage, prompts for missing params, handles errors withprocess.exitCode = 1, and ensures cleanup viacloseDarwinKit().- Good use of
@clack/promptsspinner for user feedback during command execution.
96-133: LGTM!The
promptForParamfunction handles all parameter types correctly:
- Choices-based params use
multiselectorselectappropriately.- Boolean params use
confirmwith sensible defaults.- Number params validate input and respect defaults on empty input.
- String params validate required fields and return defaults when appropriate.
The
withCanceland cancellation handling follows coding guidelines for graceful cancellation.Also applies to: 152-199
201-219: LGTM!The
buildUsageLinefunction generates clear usage hints with proper syntax for positional arguments (<required>vs[optional]) and flags.src/darwinkit/index.ts (4)
55-97: LGTM!The
buildProgramfunction correctly wires Commander:
- Positional arguments use
<required>vs[optional]syntax.- Flag options use appropriate type-based syntax (
--flag,--flag <value>,--flag <values...>).- Default values are shown in descriptions using
SafeJSON.stringify.- Format option is added to all subcommands.
99-174: LGTM!The
handleCommandActionfunction properly handles:
- Positional argument extraction from
actionArgs.- Flag processing with camelCase conversion and type coercion.
- Number validation with clear error messages.
- Format option validation against a
Setof valid values (addresses past review).- Required parameter check including empty arrays (addresses past review).
- Interactive fallback for TTY with missing params.
- Exit code 1 for non-TTY missing params (addresses past review).
- Proper error handling and
closeDarwinKit()cleanup in finally.
176-214: LGTM!The
mainfunction correctly implements the CLI flow:
- No args + TTY → interactive menu.
- No args + non-TTY → full help output.
- Args present → Commander parsing.
- Error handling with appropriate exit codes and cleanup.
3-3: parseVariadic implementation correctly handles all comma-separated value patterns.The utility at
src/utils/cli.ts(lines 12-30) properly:
- Splits by comma and trims whitespace from each element
- Filters out empty strings after trimming
- Handles both string and array inputs with appropriate type narrowing
- Uses no type assertions, following the coding guidelines
No action needed.
Comment on lines
+39
to
+41
| /** | ||
| * Delete a file from iCloud Drive. | ||
| */ |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Trim the JSDoc blocks that only restate the wrapper name.
These summaries don't add anything beyond the exported function names. I'd keep the comments that carry actual contract/usage detail, but drop the boilerplate ones on the simple delete/copy/list/stop-monitoring pass-throughs.
As per coding guidelines, "Don't add comments that restate what the code already says (e.g., obvious descriptions of function calls)".
Also applies to: 53-55, 60-62, 83-85
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utils/macos/icloud.ts` around lines 39 - 41, Remove the trivial JSDoc
blocks that merely restate the exported wrapper names for the simple
pass-through functions (the exported functions named delete, copy, list and
stopMonitoring in this module); delete those boilerplate comments (lines
currently summarizing "Delete a file from iCloud Drive.", similar summaries at
53-55, 60-62, 83-85) and only keep or expand JSDoc where it conveys actual
contract/usage details (parameters, return value, errors) for the corresponding
function implementations.
- Add return after sub.outputHelp() for explicit process exit (t1/t6) - Fix icloudList doc to reflect flat ICloudDirEntry[] return (t2) - Add missing commands: classify-batch, group-by-category, icloud-write-bytes, icloud-start-monitoring, icloud-stop-monitoring (t3) - Split comma-separated string[] args and validate numeric input (t4) - Forward --format flag to interactive fallback (t5) - Validate --format option values (t7) - Handle empty string for string[] interactive params (t8) - Add onIcloudFilesChanged subscription wrapper (t9)
- Add parseVariadic() to src/utils/cli.ts for correct Commander variadic option handling with comma-separated values - Remove duplicate --format from parent program (Commander routed value to parent opts, subcommand always fell back to json) - Add unbox option to SafeJSON.parse to unwrap boxed primitives from comment-json without losing comment support - Add 58 E2E tests covering all darwinkit commands
- Exit 1 (not 0) for missing required args in non-TTY mode - Validate --format before interactive fallback - Set process.exitCode=1 on interactive command failure - Treat empty string[] as missing in interactive prompts - Use comment-json's no_comments flag for unbox (no manual valueOf) - Add reviver to ParseOptions detection in SafeJSON.parse - Update icloud monitoring doc to reference exported wrapper - Stricter test assertions, remove redundant comments
- Add biome-ignore for JSON usage in standalone hook script - Replace JSON.stringify with SafeJSON.stringify in telegram ask
genesiscz
force-pushed
the
feat/darwinkit-utils
branch
from
5ef46d5 to
0d4d3f0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
src/utils/macos/with auth, system, and iCloud util wrapperstools darwinkitCLI tool with 30+ commands across 8 groups (NLP, Vision, Text Analysis, Classification, TTS, Auth, iCloud, System)--format json|pretty|rawoutput control, smart defaults (pretty for TTY, json for pipe)Features
tools darwinkit(TTY) — interactive menu with DarwinKit logotools darwinkit(non-TTY) — full help listing all commandstools darwinkit <cmd> <args>— direct executiontools darwinkit <cmd>(TTY, missing params) — interactive prompts for missing paramsTest plan
tsgo --noEmit— zero errorsbunx biome check— zero errorsbun test— all existing tests pass (10 pre-existing failures unrelated)Summary by CodeRabbit
New Features
Tests