Distillation

Date: Sep 10, 2026

• 🔴 (00:24) User directed contributors to always check package.json for the latest scripts.
• 🔴 (00:24) User stated all packages must be added to devDependencies, never dependencies, because everything is bundled at build time via esbuild; CI enforces this with pnpm run check:deps.
• 🔴 (00:24) User directed that packages always be added with pnpm add -D <package> using the -D flag.
• 🔴 (00:24) User stated the project uses Node.js node:* APIs and has no Bun runtime; the project was migrated from Bun.
• 🔴 (00:24) User stated user-controlled values must be passed safely to avoid shell injection.
• 🔴 (00:24) User directed never to pass a per_page value larger than API_MAX_PER_PAGE to the API because the server silently caps it, causing commands to return fewer items than requested.
• 🔴 (00:24) User stated custom command-documentation fragments are edited in docs/src/fragments/commands/.
• 🔴 (00:24) User stated silent catch blocks are prohibited in src/ production code. Biome’s noEmptyBlockStatements detects syntactically empty catch {} blocks, but blocks containing only return and no logging are also prohibited because they silently discard errors and impede debugging.
• 🔴 (00:24) User stated error resources can use " and " for plural grammar; example: "Trace ID and span ID" produces “are required.”
• 🔴 (00:24) User stated property-based test properties should always hold regardless of input.
• 🔴 [requested-tests] (00:24) User directed that when a *.property.test.ts file exists for a module, unit tests must not re-check the same invariants with hardcoded examples; before adding a unit test, contributors must check whether the companion property file already generates random inputs for that invariant.
• 🔴 (00:24) User identified property-based test placement as *.property.test.ts under test/lib/.
• 🔴 (00:24) User identified DB operations as belonging under src/lib/db/.
• 🔴 (00:24) User referenced createIsolatedDbContext and DEFAULT_NUM_RUNS from ../../model-based/helpers.js for model-based testing.
• 🔴 (00:24) User referenced useTestConfigDir("my-test-prefix-") for isolated test configuration directories.
• 🟡 (00:24) Repository validation found the working tree clean; both requested commits exist, and their merge base is exactly ec83887a16f780f32fba4b7d710bad262dba3a22.
• 🔴 (00:24) packages/cli/.cursor/rules/ultracite.mdc defines “Ultracite Rules - AI-Ready Formatter and Linter,” applies to **/*.{ts,tsx,js,jsx,json,jsonc,html,vue,svelte,astro,css,yaml,yml,graphql,gql,md,mdx,grit}, and sets alwaysApply: false.
• 🔴 (00:24) packages/cli/.cursor/rules/ultracite.mdc states the project uses Ultracite, a zero-config Biome preset enforcing strict automated formatting and linting.
• 🔴 (00:24) Ultracite commands documented in packages/cli/.cursor/rules/ultracite.mdc: format with npx ultracite fix, check with npx ultracite check, and diagnose setup with npx ultracite doctor; contributors should run npx ultracite fix before committing.
• 🔴 (00:24) Ultracite’s core objective is accessible, performant, type-safe, maintainable code, prioritizing clarity and explicit intent over brevity.
• 🔴 (00:24) Ultracite type-safety rules: use explicit function parameter and return types when they improve clarity; prefer unknown over any for genuinely unknown values; use as const for immutable values and literal types; prefer TypeScript narrowing over assertions; replace magic numbers with descriptively named constants.
• 🔴 (00:24) Ultracite modern JavaScript/TypeScript rules: use arrow functions for callbacks and short functions; prefer for...of over .forEach() and indexed for loops; use optional chaining ?. and nullish coalescing ??; prefer template literals to concatenation; use destructuring; default to const, use let only for reassignment, and never use var.
• 🔴 (00:24) Ultracite async rules: always await promises in async functions and use their return values; prefer async/await over promise chains; handle async errors appropriately with try-catch; never use async functions as Promise executors.
• 🔴 (00:24) Ultracite error-handling rules: remove console.log, debugger, and alert from production code; throw descriptive Error objects rather than strings or other values; use try-catch meaningfully rather than merely catching and rethrowing; prefer early returns for error cases.
• 🔴 (00:24) Ultracite code-organization rules: keep functions focused and within reasonable cognitive-complexity limits; extract complex conditions into well-named booleans; reduce nesting with early returns; avoid nested ternaries in favor of simple conditionals; group related code and separate concerns.
• 🔴 (00:24) Ultracite security rules: add rel="noopener" to links using target="_blank"; avoid dangerouslySetInnerHTML unless absolutely necessary; do not use eval() or assign directly to document.cookie; validate and sanitize user input.
• 🔴 (00:24) Ultracite performance rules: avoid spread syntax in loop accumulators; define regex literals at top level rather than inside loops; prefer specific imports over namespace imports; avoid barrel/index files that re-export everything; use proper image components such as Next.js <Image> instead of <img>.
• 🔴 [requested-tests] (00:24) Ultracite testing rules: assertions belong inside it() or test() blocks; async tests should use async/await rather than done callbacks; committed code must not contain .only or .skip; test suites should remain reasonably flat and avoid excessive describe nesting.
• 🔴 (00:24) packages/cli/.cursor/rules/ultracite.mdc identifies six areas requiring human attention beyond Biome, in order: 1. business-logic correctness and algorithms, 2. meaningful function/variable/type naming, 3. architecture decisions covering component structure, data flow, and API design, 4. edge cases including boundaries and errors, 5. user experience including accessibility, performance, and usability, 6. documentation for complex logic while preferring self-documenting code.