Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# CLAUDE.md

Last verified: 2026-03-07

## Monorepo Structure

Three npm workspaces:

- **`plugin/`** - Obsidian plugin source code (TypeScript, React, Vite)
- **`docs/`** - Documentation site (Docusaurus)
- **`scripts/`** - Release and code generation scripts

Each workspace has its own `package.json` and commands. See workspace-specific `CLAUDE.md` files for details.

## Top-Level Commands

- `npm run gen` - Run code generation scripts (delegates to `scripts/` workspace)

## Shared Tooling

- **Biome** (`biome.json` at root) - Linting and formatting for all TypeScript/React code
- **TypeScript** - Shared at root, workspace-specific `tsconfig.json` files
- **Vite** - Build tooling shared at root, configured per workspace

## Project-Wide Conventions

- No default exports (enforced by Biome `noDefaultExport` rule)
- All user-facing text in the plugin must use i18n (see `plugin/CLAUDE.md`)
- Run lint/format checks from the workspace directory: `npm run lint:check` / `npm run lint:fix`
3 changes: 2 additions & 1 deletion biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,8 @@
"overrides": [
{
"includes": [
"**/*.test.ts"
"**/*.test.ts",
"**/*.test.tsx"
],
"linter": {
"rules": {
Expand Down
49 changes: 11 additions & 38 deletions docs/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,26 @@
# CLAUDE.md
# Docs CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Last verified: 2026-03-07

## Project Overview
## Commands

This is the documentation site for the Sync with Todoist Plugin for Obsidian. The site is built using Docusaurus and contains user guides, configuration instructions, and contributing information.
All commands run from this `docs/` directory:

## Common Commands

All commands should be run from this `docs/` directory:

### Development

- `npm start` - Start local development server (usually runs on http://localhost:3000)
- `npm start` - Start local development server
- `npm run build` - Build documentation site for production
- `npm run serve` - Serve built site locally
- `npm run clear` - Clear Docusaurus cache

### Documentation Management

- `npm run bump-version -- ${VERSION}` - Create new versioned documentation (e.g., `npm run bump-version -- 2.2.0`)
- `npm run bump-version -- ${VERSION}` - Create new versioned docs (e.g., `npm run bump-version -- 2.2.0`)
- `npm run write-translations` - Extract translatable strings
- `npm run write-heading-ids` - Add heading IDs to markdown files

### Quality

- `npm run typecheck` - Run TypeScript type checking
- `npm run typecheck` - TypeScript type checking

## Documentation Structure

### Core Documentation (`docs/`)

- `overview.md` - Main plugin introduction and features
- `setup.md` - Installation and initial configuration
- `configuration.md` - Detailed plugin settings
- `query-blocks.md` - Query language documentation
- `changelog.md` - Version history and changes

### Commands Documentation (`docs/commands/`)

- `add-task.md` - Creating tasks from Obsidian
- `sync-with-todoist.md` - Manual sync functionality

### Contributing Documentation (`docs/contributing/`)

- `general.md` - Development setup and workflow
- `release-process.md` - How to release new versions
- `translation.mdx` - Translation contribution guide
- `docs/` - Current documentation (markdown/MDX)
- `docs/commands/` - Command-specific docs
- `docs/contributing/` - Developer and contributor guides
- `sidebars.ts` - Navigation structure (update when adding new pages)

## Versioned Documentation

Expand Down Expand Up @@ -83,7 +57,6 @@ The site supports versioned documentation with past versions stored in:
### Managing Versions

- Only cut new documentation versions for minor/major releases
- Patch releases typically don't need new doc versions
- Version bumping copies current docs to versioned storage

### Translation Support
Expand Down
118 changes: 27 additions & 91 deletions plugin/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,80 +1,39 @@
# CLAUDE.md
# Plugin CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Last verified: 2026-03-07

## Project Overview
## Commands

This is the main plugin source code for an unofficial Obsidian plugin that enables bidirectional sync between Obsidian and Todoist. The plugin allows users to view, create, and manage Todoist tasks directly within Obsidian using code blocks and modal interfaces.
All commands run from this `plugin/` directory:

## Common Commands

All commands should be run from this `plugin/` directory:

### Development

- `npm run dev` - Build plugin in development mode with type checking
- `npm run build` - Build plugin for production
- `npm run check` - Run TypeScript type checking only

### Testing and Quality

- `npm run test` - Run all tests with Vitest
- `npm run dev` - Development build with type checking
- `npm run build` - Production build
- `npm run check` - TypeScript type checking only
- `npm run test` - Run all tests (Vitest)
- `npm run test ./src/utils` - Run tests for specific directory/file
- `npm run lint:check` - Check code formatting and linting with BiomeJS
- `npm run lint:check` - Check formatting and linting (BiomeJS)
- `npm run lint:fix` - Auto-fix formatting and linting issues

## Architecture Overview

### Plugin Structure

- **Main Plugin** (`src/index.ts`): Core plugin class that initializes services, registers commands, and handles Obsidian lifecycle
- **API Layer** (`src/api/`): Todoist REST API client with domain models for tasks, projects, sections, and labels
- **Query System** (`src/query/`): Markdown code block processor that renders Todoist queries in notes
- **UI Components** (`src/ui/`): React-based user interface components including modals, settings, and task displays
- **Services** (`src/services/`): Business logic layer including token management and modal orchestration
- **Data Layer** (`src/data/`): Repository pattern for caching and managing Todoist data with transformations

### Key Components

- **Query Injector** (`src/query/injector.tsx`): Processes `todoist` code blocks and renders interactive task lists
- **Repository Pattern** (`src/data/repository.ts`): Generic caching layer for API data with sync capabilities
- **Settings Store** (`src/settings.ts`): Zustand-based state management for plugin configuration
- **Token Accessor** (`src/services/tokenAccessor.ts`): Secure storage and retrieval of Todoist API tokens

### UI Architecture

- Built with React 19 and React Aria Components
- Uses Framer Motion for animations
- SCSS with component-scoped styles
- Supports both light and dark themes matching Obsidian

### Query Language
## Project Structure

The plugin supports a custom query language in `todoist` code blocks with options for:

- Filtering tasks by project, labels, due dates
- Sorting by priority, date, order
- Grouping by project, section, priority, date, labels
- Metadata display toggles for due dates, projects, labels, descriptions

## Development Environment

### Local Development

Set `VITE_OBSIDIAN_VAULT` in `.env.local` to automatically copy build output to your Obsidian vault for testing:

```
export VITE_OBSIDIAN_VAULT=/path/to/your/obsidian/vault
```
- `src/index.ts` - Plugin entry point; initializes services, registers commands
- `src/api/` - Todoist REST API client and domain models
- `src/data/` - Repository pattern for caching API data with sync
- `src/query/` - Custom query language parser and `todoist` code block renderer
- `src/ui/` - React components (React 19 + React Aria Components + Framer Motion)
- `src/services/` - Business logic (token management, modal orchestration)
- `src/commands/` - Obsidian command definitions
- `src/i18n/` - Internationalization (interface in `translation.ts`, implementations in `langs/`)
- `src/utils/` - Shared utilities

### Code Style
## Key Design Decisions

- Uses BiomeJS for formatting and linting
- 2-space indentation, 100 character line width
- Automatic import organization with package/alias/path grouping
- React functional components with hooks
- **Repository pattern** (`src/data/repository.ts`): Generic caching layer that decouples UI from API fetch timing. All Todoist data flows through repositories.
- **Zustand for settings** (`src/settings.ts`): Reactive state management for plugin configuration, avoids prop drilling.
- **React Aria Components**: Accessibility-first UI primitives. Prefer these over custom interactive elements.
- **SCSS with component-scoped styles**: Each component has co-located `.scss`; supports Obsidian light/dark themes.

### Internationalization
## Internationalization

- **Always use translations for user-facing text** - never hardcode strings in UI components
- Import translations with `import { t } from "@/i18n"` and use `const i18n = t().section`
Expand All @@ -87,9 +46,9 @@ export VITE_OBSIDIAN_VAULT=/path/to/your/obsidian/vault
deleteNotice: (itemName: string) => string;

// en.ts
deleteNotice: (itemName: string) => `Item "${itemName}" was deleted`,
deleteNotice: ((itemName: string) => `Item "${itemName}" was deleted`,
// component.tsx
new Notice(i18n.deleteNotice(item.name));
new Notice(i18n.deleteNotice(item.name)));
```

- Translation files are in `src/i18n/` with interface in `translation.ts` and implementations in `langs/`
Expand All @@ -98,26 +57,3 @@ export VITE_OBSIDIAN_VAULT=/path/to/your/obsidian/vault

- Vitest with jsdom environment for React component testing
- Mocked Obsidian API (`src/mocks/obsidian.ts`)
- Tests focus on data transformations and utility functions

## File Organization

- `src/api/` - Todoist API client and domain models
- `src/commands/` - Obsidian command definitions
- `src/data/` - Data layer with repositories and transformations
- `src/i18n/` - Internationalization support
- `src/query/` - Query parsing and code block processing
- `src/services/` - Business logic and service layer
- `src/ui/` - React components organized by feature
- `src/utils/` - Shared utility functions

## Build Process

Uses Vite with:

- TypeScript compilation with path aliases
- React JSX transformation
- SCSS processing
- Library mode targeting CommonJS for Obsidian compatibility
- Manifest copying and build stamping
- Development mode auto-copying to vault
Loading