md-anything copilot-instructions.md

Copilot instructions for md-anything

Build, test, and lint commands

Use Bun throughout this repository.

bun install
bun run lint
bun run build

# Full suite
bun test
bun run test

# Contributor-safe required subset
bun run test:required

# Regenerate generated PDF/EPUB fixtures when needed
bun run test:fixtures

# Run a single test file
bun test tests/unit/detect-input.test.ts

# Run one test by name
bun test tests/integration/convert-text.test.ts -t "converts .txt file to markdown"

# Live/network tests
LIVE_TESTS=1 bun test tests/integration/youtube-live.test.ts tests/integration/url-live.test.ts

When debugging optional local tool support, run bun run src/cli.ts doctor.

High-level architecture

• src/cli.ts and src/mcp.ts are the shipped entry points. They both build a runtime with createRuntimeProviders(DEFAULT_CONFIG) and delegate to shared core logic instead of implementing format-specific behavior themselves.

• The main conversion path lives in src/core/convert.ts: validate with ConvertRequestSchema, detect the input kind, route with routeInput, normalize quality metadata with finalizeDocument, attach chunk/provenance data, and render Markdown with formatMarkdown.

• src/providers/* contains one converter per input kind. Providers return a NormalizedDocument; they should not format final Markdown themselves.

• Runtime capability checks are centralized in src/core/runtime.ts. Optional tools such as tesseract, pdftotext, ebook-convert, unzip, ffmpeg, whisper-cpp, and whisper are detected once and then passed through the runtime so providers can gate behavior consistently.

• src/core/ingest.ts walks supported files in a folder, converts them through the shared pipeline, and returns counts plus per-document metadata. It does not currently process source manifests or generate graph/index artifacts.

• src/mcp-support.ts is the MCP policy layer: it restricts local paths to the current workspace root, blocks private URLs by default, and defines structured tool output, resources, and prompts.