domscribe: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Detailed conventions, testing patterns, and architecture decisions are in .claude/rules/.

What is Domscribe?

Domscribe is a pixel-to-code development tool that lets developers click elements in running web apps, captures runtime context (props, state, events), and maps them to exact source locations for handoff to coding agents via MCP.

How to Work on This Codebase

Read before writing. Understand the existing patterns in a package before adding code. Match the style of what's already there.

Core principles:

• Schema-first — Define Zod schemas, derive types with z.infer<>. Never hand-write interfaces that duplicate schema shapes.
• Named exports only — No default exports. Barrel index.ts files define the public API.
• Module boundaries are enforced — Check tags in project.json before adding cross-package imports. If the boundary disallows it, rethink the design — don't just add a tag.
• ESM with .js extensions — All imports use .js extension (compiled output). Module system is nodenext.
• Constructor DI — Dependencies injected via private readonly constructor params. No service locators or global containers.

Testing:

• Unit tests mock dependencies. Use vi.mock() and vi.fn(). Constructor DI makes this clean.
• Don't spy on globals (console, etc.) — test behavior, not log output.
• Test-fixtures is the black-box layer — integration/e2e tests there have zero @domscribe/* imports. They build real apps and validate outputs.
• Relay is the exception — its unit tests use real services with temp directories (integration-style).

Don't over-engineer. Match the complexity of existing code. No premature abstractions, no speculative features, no redundant tests.

Commands

# Install dependencies (pnpm, NOT npm)
pnpm install

# Build, lint, and test all packages (excludes test-fixtures)
pnpm build:all

# Build only affected packages
pnpm build:affected

# Single package operations
nx build domscribe-core
nx test domscribe-core
nx lint domscribe-core
nx typecheck domscribe-core

# Run specific tests
nx test domscribe-core -- --testPathPattern=annotation
nx test domscribe-core -- -t "test name"

# Integration tests (test-fixtures package)
nx integration domscribe-test-fixtures

# E2E tests (requires Verdaccio + published packages)
nx e2e domscribe-test-fixtures
# Skip env vars: SKIP_SETUP=1, SKIP_PUBLISH=1, SKIP_INSTALL=1

# Local registry pipeline
pnpm release:local          # build → version → sync-dist → publish to Verdaccio
pnpm pipeline:full           # publish → install fixtures → integration + e2e
pnpm pipeline:e2e            # publish → install fixtures → e2e only

# Verdaccio (local npm registry on port 4873)
npx verdaccio --config .verdaccio/config.yml --listen 4873