add-new-file

name	add-new-file
description	Guide for adding new files to this codebase while respecting architectural principles including Separation of Concerns, Common Closure Principle, small composable functions (max 20 lines), and externalizing constants. Use when creating new modules, utilities, or any new source files in the project.

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 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:

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

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

Step 3: Externalize Constants

Create constants.ts:

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:

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

Verification Commands

After creating new files:

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