npm package: @flightdev/helpers
Description: Optional helper utilities for Flight Framework. Suggestions, not impositions.
Latest version: 0.1.1

# @flightdev/helpers

Optional helper utilities for Flight Framework. **Suggestions, not impositions.**

## Philosophy

This package provides utilities that **suggest** configurations based on your project. It never applies anything automatically. You decide whether to use the suggestions or not.

## Installation

```bash
npm install @flightdev/helpers
```

## Usage

### Detect UI Framework

```typescript
import { detectFramework } from '@flightdev/helpers/detect';

const result = await detectFramework();

console.log(result);
// {
//   framework: 'react',
//   confidence: 'high',
//   source: 'package.json',
//   reasoning: 'Found react and react-dom in dependencies'
// }

// You decide what to do with this information
if (result.framework) {
  console.log(`Detected: ${result.framework}`);
} else {
  console.log('No framework detected, using vanilla');
}
```

### Detect Deployment Target

```typescript
import { detectDeploymentTarget } from '@flightdev/helpers/detect';

const result = await detectDeploymentTarget();

console.log(result);
// {
//   adapter: 'vercel',
//   confidence: 'high',
//   source: 'environment',
//   reasoning: 'VERCEL environment variable detected'
// }

// You decide whether to use this
console.log(`Suggested adapter: ${result.adapter}`);
console.log(`To install: npm install @flightdev/adapter-${result.adapter}`);
```

### Suggest Defaults

```typescript
import { suggestDefaults } from '@flightdev/helpers/suggest';

const suggestions = await suggestDefaults();

console.log(suggestions);
// {
//   framework: 'react',
//   adapter: 'vercel',
//   rendering: 'ssr',
//   bundler: 'vite',
//   confidence: {
//     framework: 'high',
//     adapter: 'high'
//   }
// }

// Use in your config if you want
// flight.config.ts
import { defineConfig } from '@flightdev/core';

export default defineConfig({
  ui: {
    // Use suggestion or override
    framework: suggestions.framework ?? 'react',
  },
});
```

## API Reference

### detectFramework(root?: string)

Detects the UI framework used in the project.

**Returns:**
```typescript
interface FrameworkDetection {
  framework: 'react' | 'vue' | 'svelte' | 'solid' | 'preact' | 'qwik' | 'lit' | 'htmx' | 'angular' | null;
  confidence: 'high' | 'medium' | 'low';
  source: string;
  reasoning: string;
}
```

### detectDeploymentTarget(root?: string)

Detects the deployment environment.

**Returns:**
```typescript
interface DeploymentDetection {
  adapter: 'node' | 'vercel' | 'netlify' | 'cloudflare' | 'aws' | 'docker' | 'fly' | 'deno' | 'bun' | null;
  confidence: 'high' | 'medium' | 'low';
  source: string;
  reasoning: string;
}
```

### suggestDefaults(root?: string)

Returns suggested configuration based on detected context.

**Returns:**
```typescript
interface SuggestedDefaults {
  framework: string | null;
  adapter: string | null;
  rendering: 'ssr' | 'csr' | 'ssg';
  bundler: 'vite' | 'esbuild' | 'rolldown';
  confidence: {
    framework: 'high' | 'medium' | 'low';
    adapter: 'high' | 'medium' | 'low';
  };
}
```

## Important

This package:
- **Never** applies configuration automatically
- **Never** installs packages
- **Never** modifies files
- Only **returns information** for you to use

You are always in control.

## License

MIT