add-new-file

# Add New File

This skill guides you through adding new files to the codebase while maintaining architectural consistency and code quality standards.

## Quick Reference

When adding a new file to this project:

1. **Determine the scope** - What domain/concern does this file address?
2. **Follow module pattern** - Create types.ts, constants.ts, main logic file
3. **Externalize constants** - All magic strings/numbers go in constants.ts
4. **Keep functions small** - Max 20 lines of logic per function
5. **Use proper imports** - `node:` prefix, `import type`, `.ts` extensions
6. **Write co-located tests** - Create `.test.ts` alongside source

See [references/architecture-principles.md](references/architecture-principles.md) for comprehensive guidelines.

## Adding a New Module

When creating a new module (e.g., `cache/`, `auth/`, `logger/`):

### Step 1: Create Module Directory

```
module-name/
├── types.ts          # Type definitions only
├── constants.ts      # Externalized constants
├── module-name.ts    # Core logic
└── module-name.test.ts  # Tests
```

### Step 2: Define Types First

Create `types.ts`:

```typescript
export interface ModuleConfig {
  enabled: boolean;
  timeout: number;
}

export type ModuleState = "idle" | "active" | "error";
```

### Step 3: Externalize Constants

Create `constants.ts`:

```typescript
export const DEFAULT_TIMEOUT_MS = 5000;
export const MODULE_CONFIG_FILE = "module-config.json";
export const ERROR_INVALID_CONFIG = "Invalid module configuration";
```

### Step 4: Implement Core Logic

Create `module-name.ts`:

```typescript
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import type { ModuleConfig } from "./types.ts";
import { DEFAULT_TIMEOUT_MS, MODULE_CONFIG_FILE } from "./constants.ts";

export const loadModuleConfig = (dir: string): ModuleConfig => {
  const configPath = join(dir, MODULE_CONFIG_FILE);
  if (!existsSync(configPath)) {
    return { enabled: true, timeout: DEFAULT_TIMEOUT_MS };
  }
  return JSON.parse(readFileSync(configPath, "utf-8"));
};
```

### Step 5: Write Tests

Create `module-name.test.ts` following Vitest patterns in the reference doc.

## Adding a Utility File

For standalone utilities that don't need a full module:

1. Place in appropriate existing module or create `utils/` if needed
2. Create `utils/helper.ts` and `utils/helper.test.ts`
3. Extract any constants to the parent module's `constants.ts`
4. Keep functions small and composable

## Pre-Flight Checklist

Before creating files, verify:

- ✅ **Correct location** - File belongs in right module/directory
- ✅ **Constants identified** - Know what values need externalizing
- ✅ **Types defined** - Clear interfaces for inputs/outputs
- ✅ **Single responsibility** - File has one clear purpose
- ✅ **Dependencies mapped** - Know what to import

## Post-Creation Checklist

After creating files, verify:

- ✅ **All imports use `node:` prefix** for built-ins
- ✅ **Type imports use `import type`**
- ✅ **Relative imports include `.ts` extension**
- ✅ **All exports have explicit return types**
- ✅ **Constants externalized to `constants.ts`**
- ✅ **Functions under 20 lines of logic**
- ✅ **Tests created and passing**
- ✅ **Code follows style guide** (see reference doc)
- ✅ **No `console.log` statements** (use `client.tui`)

## Common Patterns

### Configuration Module

```
config/
├── types.ts       # ConfigOptions, ConfigSchema
├── constants.ts   # CONFIG_FILE_NAME, DEFAULT_VALUES
├── config.ts      # loadConfig(), saveConfig()
└── config.test.ts
```

### Business Logic Module

```
processor/
├── types.ts          # ProcessorInput, ProcessorOutput
├── constants.ts      # MAX_RETRIES, TIMEOUT_MS
├── processor.ts      # process(), validate()
└── processor.test.ts
```

### Utility Module

```
utils/
├── string-utils.ts      # String manipulation helpers
├── string-utils.test.ts
├── path-utils.ts        # Path manipulation helpers
└── path-utils.test.ts
```

## Detailed Guidelines

For comprehensive information on:

- Complete constants externalization rules with examples
- Full code style guide (imports, functions, naming, formatting)
- Error handling patterns
- Testing patterns with Vitest
- File system operation patterns

**Read:** [references/architecture-principles.md](references/architecture-principles.md)

## Verification Commands

After creating new files:

```bash
bun run typecheck   # Verify TypeScript types
bun run lint        # Check code style
bun run test        # Run tests
bun run build       # Ensure it builds
```