# Profile Helper Usage Guide

## Quick Integration

To add profile support to any numerology tool, use the `profile-helper.ts` utility.

## Example: Before & After

### Before (without profile support)

```typescript
// Parse arguments
let name = '';
let birthdate = '';

for (let i = 0; i < args.length; i++) {
  if (args[i] === '--name' && args[i + 1]) {
    name = args[i + 1];
    i++;
  } else if (args[i] === '--birthdate' && args[i + 1]) {
    birthdate = args[i + 1];
    i++;
  }
}

if (!name || !birthdate) {
  console.error('Error: Both --name and --birthdate are required');
  process.exit(1);
}
```

### After (with profile support)

```typescript
import { parseProfileOrDirect } from './profile-helper';

// Parse arguments - automatically handles --profile or --name/--birthdate
const { name, birthdate } = parseProfileOrDirect(args, {
  toolName: 'optimal-days',
  requiresBirthdate: true,
  requiresName: false
});
```

That's it! Just 3 lines instead of 20+.

## Features

✅ Automatically handles `--profile` or `--name`/`--birthdate`
✅ Loads profile from storage
✅ Validates required fields
✅ Provides helpful error messages
✅ Consistent behavior across all tools

## Configuration Options

```typescript
interface ParseOptions {
  toolName: string;           // For error messages
  requiresBirthdate?: boolean; // Default: true
  requiresName?: boolean;      // Default: true
}
```

## Real-World Example

Here's how to retrofit an existing tool:

```typescript
#!/usr/bin/env bun
import { parseProfileOrDirect } from './profile-helper';

const args = process.argv.slice(2);

// Old way (20+ lines):
// let name = '';
// let birthdate = '';
// for (let i = 0; i < args.length; i++) {
//   if (args[i] === '--name' && args[i + 1]) { ... }
//   if (args[i] === '--birthdate' && args[i + 1]) { ... }
// }
// if (!name || !birthdate) { ... }

// New way (1 line):
const { name, birthdate } = parseProfileOrDirect(args, {
  toolName: 'advanced-numbers'
});

// Rest of your tool logic...
console.log(`Calculating for ${name} (${birthdate})`);
```

## Tools to Update

The following tools can be retrofitted:

- [ ] `advanced-numbers.ts`
- [ ] `compatibility.ts` (person1 only)
- [ ] `cycles-week.ts`
- [ ] `name-change.ts`
- [ ] `name-optimizer.ts`
- [ ] `optimal-days.ts`
- [ ] `pinnacles.ts`
- [ ] `telos-cycles-analyze.ts`
- [ ] `telos-export.ts`
- [ ] `telos-week.ts`
- [ ] `year-ahead.ts`

## Help Text Integration

Use `addProfileToHelp()` to automatically update help text:

```typescript
import { addProfileToHelp } from './profile-helper';

const helpText = `
USAGE:
  bun tool.ts --name "..." --birthdate "..." [OPTIONS]

OPTIONS:
  --name NAME          Full name [required]
  --birthdate DATE     Birthdate [required]
`;

// Automatically adds --profile option and updates [required] text
console.log(addProfileToHelp(helpText));
```

Output:
```
USAGE:
  bun tool.ts --name "..." --birthdate "..." [OPTIONS]

OPTIONS:
  -p, --profile ID      Use saved profile
  --name NAME           Full name [required if no profile]
  --birthdate DATE      Birthdate [required if no profile]
```

## Benefits

1. **DRY** - Don't repeat profile loading code
2. **Consistent** - Same behavior everywhere
3. **Maintainable** - Update once, fixes everywhere
4. **Simple** - 1-3 lines vs 20+ lines
5. **Type-safe** - TypeScript interfaces

## Next Steps

Tools can be updated individually as-needed, or all at once. The helper is ready to use!