numerology/PROFILE-HELPER-USAGE.md

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)

// 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)

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

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:

#!/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:

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!