Skip to content

CLAUDE.md

Latest commit

 

History

History
49 lines (34 loc) · 2.43 KB

CLAUDE.md

File metadata and controls

49 lines (34 loc) · 2.43 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build          # Compile TypeScript (tsc)
npm test               # Run all tests (vitest run)
npm run dev            # Watch mode compilation
npx vitest run tests/unit/config.test.ts   # Run a single test file

Build before testing — tests run against compiled dist/ for integration tests (unit tests use source directly via vitest).

Architecture

Three-layer separation: CLI → Core → Storage. The core layer has no stdout or process.exit calls, making it reusable for the future MCP server.

src/cli/          Parses args (commander), calls core, formats output
src/core/         Business logic, validation, orchestration
src/storage/      File I/O, YAML serialization
src/types/        Shared interfaces and error classes
src/utils/        Date formatting, validation helpers, emoji maps
src/web/          Inline HTML dashboard served by `tsk web`

CLI commands register via registerX(program: Command) functions in src/cli/commands/. Each command calls loadProject() to find the .tsk/ root, creates a storage instance, then delegates to core functions.

Output format is auto-detected: pretty (chalk-colored) for TTY, JSON for pipes. Global flags --json, --yaml, --quiet override. The detectFormat() → output() pipeline in src/cli/formatters/ handles all formatting.

Storage is pluggable via the TaskStorage interface. Two backends: MultiFileStorage (one .yml per task in .tsk/tasks/) and SingleFileStorage (all in .tsk/tasks.yml). Both use atomic writes (temp file + rename).

Error classes in src/types/errors.ts map to exit codes: TskError(1), TaskNotFoundError(2), InvalidFieldError(3), ConfigError/ProjectNotFoundError(4).

Key Conventions

  • All .ts imports use explicit .js extensions (Node16 module resolution)
  • CJS output — chalk is pinned to v4.1.2 (last CJS version)
  • Task IDs are sequential integers from a counter in config.yml; commands accept both 1 and TSK-1
  • Every mutation command accepts --by <name> for attribution (defaults to $USER)
  • YAML serialization strips null/undefined fields via cleanForYaml()
  • Activity entries track all changes as an append-only log on each task

Git

  • Remote uses SSH host alias github-vikasprogrammer (key: ~/.ssh/vikasprogrammer)
  • Push with: git push origin main