into-md

Imported from nbbaier/into-md (AGENTS.md). Install upstream with npx skills add nbbaier/into-md. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Source lives in src/; src/index.ts is the CLI entry point (currently a scaffold) and should orchestrate fetch → extract → convert flow described in docs/SPEC.md.
• docs/SPEC.md captures the intended CLI behavior, options, and future module layout (fetcher, extractor, converter, tables, images, metadata, cache). Mirror that structure when adding files.
• Root configs: package.json (Bun/TypeScript module), tsconfig.json (strict, bundler-style ESM), bun.lock (deps). Keep new assets alongside the code they serve and prefer co-locating fixtures/tests with their modules.

Build, Test, and Development Commands

• bun install — install dependencies.
• bun run index.ts -- <url> — run the CLI locally; currently prints a stub, expand to follow docs/SPEC.md.
• bun test — use Bun’s test runner once tests are added (no tests yet). Add focused scripts if needed, but favor Bun-native commands over npm aliases.

Coding Style & Naming Conventions

• Language: TypeScript with ESM imports; respect tsconfig.json strictness (noImplicitOverride, noUncheckedIndexedAccess, etc.).
• Formatting: 2-space indentation; favor small, pure functions and explicit return types. Keep module names descriptive (fetcher.ts, converter.ts, etc.) to match the spec.
• Error handling: surface actionable messages; prefer typed errors or result objects over silent failures. Keep side effects in the CLI layer; keep helpers deterministic.
• Dependency stance: prefer stdlib/Bun-first utilities; add new deps only when they materially reduce complexity.

Testing Guidelines

• Runner: Bun’s built-in test runner. Place tests as *.test.ts or in __tests__/ near the code under test.
• Aim for coverage on fetch/extract/convert paths, option parsing, and cache behavior. Use small HTML fixtures for extraction/markdown conversion scenarios.
• Keep tests deterministic: avoid network calls; mock fetch/playwright layers and cache I/O; freeze time where ordering matters.

Commit & Pull Request Guidelines

• Commit messages follow the existing pattern type: description (e.g., feat: bun init). Use imperative mood and keep scope narrow.
• PRs should include: summary of changes, linked issues/tasks, notable decisions or trade-offs, and sample CLI output when it changes behavior. Add screenshots only if user-facing formatting is affected.
• Keep diffs focused; prefer separate PRs for refactors vs. feature work. Update docs (README.md, docs/SPEC.md) alongside code changes that affect them.

Ultracite Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

• Format code: bun x ultracite fix
• Check for issues: bun x ultracite check
• Diagnose setup: bun x ultracite doctor

Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

• Use explicit types for function parameters and return values when they enhance clarity
• Prefer unknown over any when the type is genuinely unknown
• Use const assertions (as const) for immutable values and literal types
• Leverage TypeScript's type narrowing instead of type assertions
• Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

• Use arrow functions for callbacks and short functions
• Prefer for...of loops over .forEach() and indexed for loops
• Use optional chaining (?.) and nullish coalescing (??) for safer property access
• Prefer template literals over string concatenation
• Use destructuring for object and array assignments
• Use const by default, let only when reassignment is needed, never var

Async & Promises

• Always await promises in async functions - don't forget to use the return value
• Use async/await syntax instead of promise chains for better readability
• Handle errors appropriately in async code with try-catch blocks
• Don't use async functions as Promise executors

React & JSX

• Use function components over class components
• Call hooks at the top level only, never conditionally
• Specify all dependencies in hook dependency arrays correctly
• Use the key prop for elements in iterables (prefer unique IDs over array indices)
• Nest children between opening and closing tags instead of passing as props
• Don't define components inside other components
• Use semantic HTML and ARIA attributes for accessibility:
  • Provide meaningful alt text for images
  • Use proper heading hierarchy
  • Add labels for form inputs
  • Include keyboard event handlers alongside mouse events
  • Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

Error Handling & Debugging

• Remove console.log, debugger, and alert statements from production code
• Throw Error objects with descriptive messages, not strings or other values
• Use try-catch blocks meaningfully - don't catch errors just to rethrow them
• Prefer early returns over nested conditionals for error cases

Code Organization

• Keep functions focused and under reasonable cognitive complexity limits
• Extract complex conditions into well-named boolean variables
• Use early returns to reduce nesting
• Prefer simple conditionals over nested ternary operators
• Group related code together and separate concerns

Security

• Add rel="noopener" when using target="_blank" on links
• Avoid dangerouslySetInnerHTML unless absolutely necessary
• Don't use eval() or assign directly to document.cookie
• Validate and sanitize user input

Performance

• Avoid spread syntax in accumulators within loops
• Use top-level regex literals instead of creating them in loops
• Prefer specific imports over namespace imports
• Avoid barrel files (index files that re-export everything)
• Use proper image components (e.g., Next.js <Image>) over <img> tags

Framework-Specific Guidance

Next.js:

• Use Next.js <Image> component for images
• Use next/head or App Router metadata API for head elements
• Use Server Components for async data fetching instead of async Client Components

React 19+:

• Use ref as a prop instead of React.forwardRef

Solid/Svelte/Vue/Qwik:

• Use class and for attributes (not className or htmlFor)

Testing

• Write assertions inside it() or test() blocks
• Avoid done callbacks in async tests - use async/await instead
• Don't use .only or .skip in committed code
• Keep test suites reasonably flat - avoid excessive describe nesting

When Biome Can't Help

Biome's linter will catch most issues automatically. Focus your attention on:

1. Business logic correctness - Biome can't validate your algorithms
2. Meaningful naming - Use descriptive names for functions, variables, and types
3. Architecture decisions - Component structure, data flow, and API design
4. Edge cases - Handle boundary conditions and error states
5. User experience - Accessibility, performance, and usability considerations
6. Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Biome. Run bun x ultracite fix before committing to ensure compliance.

Agent Skills

Issue Tracker

Issues live in GitHub Issues (nbbaier/into-md); external PRs are not a triage surface. See docs/agents/issue-tracker.md.

Triage Labels

Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), no remapping. See docs/agents/triage-labels.md.

Domain Docs

Single-context layout: one CONTEXT.md + docs/adr/ at the repo root. See docs/agents/domain.md.