files

File Organization Rules

Directory Structure

src/
├── commands/     # CLI command implementations (14 commands)
│   ├── init, add, remove, sync, push, pull
│   ├── restore, status, list, diff, config
│   └── apply, undo, scan
├── lib/          # Core library modules (11 modules)
│   ├── paths, config, manifest, git, files
│   ├── backup, hooks, github, timemachine
│   └── merge, detect
├── ui/           # Terminal UI components
│   └── banner, logger, prompts, spinner, table
├── schemas/      # Zod validation schemas
│   └── config.schema, manifest.schema
├── constants.ts  # App constants
├── types.ts      # TypeScript types
├── errors.ts     # Custom error classes
└── index.ts      # Entry point

File Placement

Commands (src/commands/)

• One file per command
• Named after the command: add.ts, sync.ts
• Export named command: export const addCommand
• Register in src/commands/index.ts

Library Modules (src/lib/)

• Core functionality, reusable across commands
• Named by domain: paths.ts, git.ts, config.ts
• Export all public functions
• Register in src/lib/index.ts

UI Components (src/ui/)

• Terminal UI utilities
• Named by function: logger.ts, prompts.ts
• Wrapper around @clack/prompts, chalk, etc.
• Register in src/ui/index.ts

Schemas (src/schemas/)

• Zod validation schemas
• Named with .schema.ts suffix
• Export input and output types

Creating New Files

New Command

1. Create src/commands/mycommand.ts
2. Export from src/commands/index.ts
3. Register in src/index.ts
4. Add tests in tests/commands/mycommand.test.ts

New Library Module

1. Create src/lib/mymodule.ts
2. Export from src/lib/index.ts
3. Add tests in tests/lib/mymodule.test.ts

New Schema

1. Create src/schemas/myschema.schema.ts
2. Export input type, output type, and schema

Index Files

Always use barrel exports:

// src/lib/index.ts
export * from './paths.js';
export * from './config.js';
export * from './git.js';