openpencil/openspec/specs/tooling/spec.md

# tooling Specification

## Purpose
Build and development tooling. Vite 7 build system, oxlint linting, oxfmt formatting, typescript-go type checking, and Tailwind CSS 4 integration.
## Requirements
### Requirement: Vite 7 build system
The project SHALL use Vite 7 as the build tool with dev server at port 1420 and HMR support. Documentation lives in `packages/docs/` as `@open-pencil/docs` workspace package with its own dev/build/preview scripts.

#### Scenario: Dev server
- **WHEN** `bun run dev` is executed
- **THEN** Vite dev server starts at http://localhost:1420 with hot module replacement

#### Scenario: Docs dev
- **WHEN** `cd packages/docs && bun run dev` is executed
- **THEN** VitePress dev server starts for the documentation site

#### Scenario: Docs build
- **WHEN** `cd packages/docs && bun run build` is executed
- **THEN** VitePress builds the documentation site to `packages/docs/.vitepress/dist/`

#### Scenario: Docs preview
- **WHEN** `cd packages/docs && bun run preview` is executed
- **THEN** a static server previews the built documentation site

### Requirement: oxlint linting
The project SHALL use oxlint for fast linting with project-specific configuration in oxlint.json.

#### Scenario: Lint check
- **WHEN** `bun run lint` is executed
- **THEN** oxlint checks src/ for issues based on oxlint.json rules

### Requirement: oxfmt formatting
The project SHALL use oxfmt for code formatting with configuration in .oxfmtrc.json.

#### Scenario: Format code
- **WHEN** `bun run format` is executed
- **THEN** oxfmt formats all files in src/ according to project rules

### Requirement: typescript-go type checking
The project SHALL use typescript-go (tsgo) for type checking via `bun run typecheck`.

#### Scenario: Type check
- **WHEN** `bun run typecheck` is executed
- **THEN** tsgo --noEmit checks all TypeScript files for type errors

### Requirement: Combined check command
`bun run check` SHALL run both lint and typecheck sequentially.

#### Scenario: Full check
- **WHEN** `bun run check` is executed
- **THEN** oxlint runs first, then tsgo, and both must pass

### Requirement: Tailwind CSS 4 integration
Tailwind CSS 4 SHALL be integrated via @tailwindcss/vite plugin.

#### Scenario: Tailwind classes work
- **WHEN** a Vue component uses Tailwind utility classes
- **THEN** the corresponding CSS is generated and applied

### Requirement: @/ import alias
The project SHALL configure a `@/` → `src/` path alias in both `vite.config.ts` (resolve.alias) and `tsconfig.json` (paths). All cross-directory imports SHALL use `@/` instead of relative `../` paths. Same-directory `./` imports are kept as-is.

#### Scenario: Import with alias
- **WHEN** a component in `src/components/` imports from `src/engine/`
- **THEN** the import uses `@/engine/` instead of `../../engine/`

### Requirement: Shared types module
Shared primitive types (Vector, Matrix, Rect) SHALL be defined in `src/types.ts` and imported across the codebase. Window API declarations (File System Access, queryLocalFonts) SHALL be in `src/global.d.ts`. Inline type duplicates SHALL be eliminated.

#### Scenario: Shared Vector type
- **WHEN** multiple files need a 2D point type
- **THEN** they import `Vector` from `@/types` instead of defining their own

### Requirement: Zero lint and type errors
The codebase SHALL maintain 0 oxlint warnings and 0 tsgo type errors. `bun run check` SHALL pass cleanly.

#### Scenario: Clean check
- **WHEN** `bun run check` is executed
- **THEN** both lint and typecheck pass with zero issues

### Requirement: Bun workspace monorepo
The project SHALL use Bun workspaces with packages: root (app), packages/core (@open-pencil/core), packages/cli (@open-pencil/cli), packages/docs (@open-pencil/docs). The workspace is configured in the root package.json. CLI is runnable via `bun open-pencil` in the workspace.

#### Scenario: Workspace packages resolve
- **WHEN** the app imports from @open-pencil/core
- **THEN** Bun resolves it to packages/core/ via workspace linking

### Requirement: npm publishing preparation
@open-pencil/core and @open-pencil/cli SHALL have proper package.json fields for npm publishing: name, version, description, exports, main, types, files, license, repository.


### Requirement: Copy-paste detection
The project SHALL use jscpd for copy-paste detection. The `bun run jscpd` command SHALL scan for duplicated code blocks.

#### Scenario: Detect duplicates
- **WHEN** `bun run jscpd` is run
- **THEN** duplicated code blocks are reported with locations and percentages

### Requirement: Kiwi serialization consolidation
Shared kiwi serialization logic (sceneNodeToKiwi, buildFigKiwi, parseFigKiwiChunks, decompressFigKiwiDataAsync) SHALL be extracted to packages/core/src/kiwi-serialize.ts. The app's src/kiwi/ SHALL re-export from core, eliminating the vendored kiwi-schema copy.

#### Scenario: Clipboard and fig-export share serialization
- **WHEN** clipboard.ts and fig-export.ts serialize nodes to kiwi
- **THEN** both use the shared kiwi-serialize.ts functions

### Requirement: Test coverage script
The project SHALL include a `test:coverage` script for measuring code coverage.

#### Scenario: Run coverage
- **WHEN** `bun run test:coverage` is run
- **THEN** test coverage metrics are reported

### Requirement: Unified tool definitions

The project SHALL define design tools once in `packages/core/src/tools/` and adapt them for AI, CLI, and MCP contexts.

#### Scenario: Canonical tool schema
- **WHEN** a new tool is added
- **THEN** it is defined in `packages/core/src/tools/schema.ts` as the single source of truth

#### Scenario: AI adapter
- **WHEN** AI assistant needs tool definitions
- **THEN** `packages/core/src/tools/ai-adapter.ts` converts schema to LLM-compatible format

#### Scenario: CLI adapter
- **WHEN** CLI commands use tools
- **THEN** citty commands consume tool schema directly

#### Scenario: MCP adapter (future)
- **WHEN** MCP server integration is added
- **THEN** MCP protocol adapter converts tool schema to MCP format

### Requirement: Tool schema structure

Tool schemas SHALL be defined in `packages/core/src/tools/schema.ts` with name, description, parameters (with types and descriptions), and handler function.

#### Scenario: Tool definition format
- **WHEN** defining a tool in schema.ts
- **THEN** structure includes `{ name, description, parameters: { <param>: { type, description } }, handler: (params) => result }`

#### Scenario: Type-safe parameters
- **WHEN** tool is invoked
- **THEN** parameters are validated against schema types

### Requirement: Deduplication of AI tools

The project SHALL eliminate duplication in `src/ai/tools.ts` by using `FigmaAPI.toJSON()` for node serialization and shared color parsing from `packages/core/src`.

#### Scenario: Node serialization
- **WHEN** AI tool returns node data
- **THEN** it uses `figmaAPI.toJSON(node)` instead of custom JSON builders

#### Scenario: Color parsing
- **WHEN** AI tool parses color input
- **THEN** it uses `parseColor()` from core instead of inline regex

#### Scenario: Code reduction
- **WHEN** AI tools are refactored
- **THEN** 311 lines are removed from `src/ai/tools.ts` via deduplication

### Requirement: Shared tool testing

The project SHALL provide test suites for tools in `tests/engine/tools.test.ts`, `tests/engine/tools-ai-adapter.test.ts`, and `tests/engine/tools-cli.test.ts`.

#### Scenario: Tool schema tests
- **WHEN** `tests/engine/tools.test.ts` runs
- **THEN** each tool schema is validated for structure and handler execution

#### Scenario: AI adapter tests
- **WHEN** `tests/engine/tools-ai-adapter.test.ts` runs
- **THEN** AI tool format conversion is verified

#### Scenario: CLI adapter tests
- **WHEN** `tests/engine/tools-cli.test.ts` runs
- **THEN** CLI command integration with tool schema is verified

### Requirement: Tool handler execution

Tool handlers SHALL receive parameters as plain objects and return structured results (success/error, data).

#### Scenario: Successful tool execution
- **WHEN** tool handler is invoked with valid params
- **THEN** it returns `{ success: true, data: <result> }`

#### Scenario: Tool execution error
- **WHEN** tool handler encounters error
- **THEN** it returns `{ success: false, error: "message" }`

### Requirement: Tool documentation

Each tool in schema.ts SHALL have clear description and parameter documentation for AI/human comprehension.

#### Scenario: Tool description
- **WHEN** AI queries available tools
- **THEN** description explains what the tool does (e.g., "Create a rectangle with specified dimensions and position")

#### Scenario: Parameter descriptions
- **WHEN** AI reads parameter schema
- **THEN** each parameter has type and description (e.g., `width: { type: 'number', description: 'Rectangle width in pixels' }`)


### Requirement: CHANGELOG
The project SHALL maintain a CHANGELOG.md in the root following Keep a Changelog conventions.

#### Scenario: Changelog exists
- **WHEN** user reads CHANGELOG.md
- **THEN** version history with categorized changes (Editor, CLI, File Format, etc.) is listed

### Requirement: npm trusted publishing
Package configs SHALL include `repository` field and `provenance: true` for npm trusted publishing via GitHub Actions.

#### Scenario: Publish with provenance
- **WHEN** GitHub Actions release workflow runs
- **THEN** packages are published to npm with provenance attestation

### Requirement: CI app deployment
The project SHALL have a GitHub Actions workflow (`app.yml`) for deploying the web app to app.openpencil.dev.

#### Scenario: App deploys on push
- **WHEN** code is pushed to main branch
- **THEN** GitHub Actions builds and deploys the app