Configuration and CLI Option Types

Relevant Source Files

• src/cli/adopt.ts
• src/cli/config.ts
• src/cli/review.ts
• src/types.ts
• test/cli-commands.test.ts
• test/types-difficulty.test.ts

This page details the technical implementation of the PALEE configuration system and the TypeScript interfaces governing CLI command options. The configuration system manages persistent settings such as the vault location and AI preferences, while the CLI option types ensure type-safe interaction between the command-line interface and the engine core.

Configuration System

PALEE uses a JSON-based configuration file to store user preferences. The configuration is managed via the PaleeConfig interface and accessed through platform-specific paths.

PaleeConfig Interface

The PaleeConfig interface defines the core settings required for PALEE to operate src/types.ts#104-108

Property	Type	Description
vaultPath	string (optional)	The absolute path to the Obsidian vault containing the Markdown notes.
aiProvider	string (optional)	The LLM provider for AI-assisted features (e.g., "openai", "anthropic").
model	string (optional)	The specific model identifier to use for AI tasks.

Config File Resolution

The location of config.json is determined by the getConfigPath function src/cli/config.ts#11-25 which follows platform-specific conventions:

1. Environment Override: If the PALEE_CONFIG_DIR environment variable is set, the config is stored in ${PALEE_CONFIG_DIR}/config.jsonsrc/cli/config.ts#12-14 This is primarily used for test isolation test/cli-commands.test.ts#27
2. Windows: %LOCALAPPDATA%\palee\config.jsonsrc/cli/config.ts#16-21
3. POSIX (Linux/macOS): ~/.config/palee/config.jsonsrc/cli/config.ts#23

Configuration Flow

The loadConfig function reads the JSON file and returns a PaleeConfig object. If the file does not exist (ENOENT), it returns an empty object src/cli/config.ts#27-39 The saveConfig function ensures the directory exists before writing the updated configuration back to disk src/cli/config.ts#41-50

Sources:

• src/types.ts#104-108
• src/cli/config.ts#11-50
• test/cli-commands.test.ts#23-35

Difficulty Normalization

The Difficulty type is a union of 'beginner', 'intermediate', and 'advanced'src/types.ts#21 Because users may provide difficulty levels as numbers (1-5) or varied strings, the system employs a normalizeDifficulty function src/types.ts#29-47

Mapping Logic

• Numbers: 1 maps to beginner; 2-3 maps to intermediate; 4-5 maps to advancedsrc/types.ts#41-45
• Strings: Case-insensitive matching for canonical names. Stringified numbers are parsed and mapped using the number logic src/types.ts#30-40
• Fallback: Defaults to intermediate for null, undefined, or invalid inputs src/types.ts#46

Sources:

• src/types.ts#21-47
• test/types-difficulty.test.ts#5-50

CLI Option Interfaces

Each CLI command has a corresponding TypeScript interface that defines its accepted flags and arguments. This ensures that the command handlers receive correctly typed data from the CLI entry point.

Command Option Summary

Interface	Command	Properties
AdoptOptions	palee adopt	difficulty (Difficulty), dependsOn (string) src/types.ts#168-171
NextOptions	palee next	all (boolean), json (boolean) src/types.ts#173-176
PlanOptions	palee plan	json (boolean) src/types.ts#178-180
DashboardOptions	palee dashboard	json (boolean) src/types.ts#182-184
ProgressOptions	palee progress	topic (string), json (boolean) src/types.ts#186-189
ValidateOptions	palee validate	fix (boolean), json (boolean), strict (boolean) src/types.ts#564-578
RoadmapOptions	palee roadmap	from (string), yes (boolean) src/types.ts#202-205
SessionOptions	palee session	interactive (boolean), topic (string), json (boolean) src/types.ts#196-200

Implementation Detail: Adopt Command

The adoptCommand utilizes AdoptOptions to initialize a note's frontmatter. It validates that the difficulty provided matches valid inputs (beginner, intermediate, advanced, or 1-5) before calling normalizeDifficultysrc/cli/adopt.ts#53-62

Sources:

• src/types.ts#166-206
• src/cli/adopt.ts#20-107

Data Flow Diagrams

Configuration and File Resolution

This diagram bridges the natural language concept of "Platform Specific Config" to the code entities responsible for resolving paths and loading data.

Sources:

• src/cli/config.ts#11-39
• src/types.ts#104-108

Command Option Processing

This diagram illustrates how CLI inputs are transformed into typed options and then into vault modifications, using the adopt command as an example.

Sources:

• src/types.ts#168-171
• src/cli/adopt.ts#53-91
• src/storage/frontmatter.ts#88
• src/storage/atomic-write.ts#91