npm package: @flughafen/cli
Description: Command-line interface for Flughafen GitHub Actions workflow builder
Latest version: 0.0.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @flughafen/cli

Command-line interface for Flughafen - Type-safe GitHub Actions workflow builder.

## Status

✅ **Stable** - Core commands operational. Validation features under active development.

## Installation

```bash
# Install as dev dependency (recommended)
pnpm add -D @flughafen/cli

# Or install globally
npm install -g @flughafen/cli
```

## Commands

### Build Workflows

Build TypeScript workflows to YAML:

```bash
# Build all workflows in default directory
flughafen build

# Build specific file
flughafen build workflows/ci.ts

# Build with output directory
flughafen build workflows/ci.ts --output .github/workflows
```

### Validate Workflows

Validate workflow syntax and structure:

```bash
# Validate workflow file
flughafen validate workflows/ci.ts

# Validate with strict mode
flughafen validate workflows/ci.ts --strict

# Validation only (no generation)
flughafen validate workflows/ci.ts --validate-only
```

### Reverse Engineering

Convert existing YAML workflows to TypeScript:

```bash
# Convert single workflow
flughafen reverse .github/workflows/ci.yml

# Convert entire directory
flughafen reverse .github

# With options
flughafen reverse .github \
  --output ./workflows \
  --extract-local-actions \
  --verbose

# Preview without writing files
flughafen reverse .github --preview

# Extract only local actions
flughafen reverse .github --local-actions-only
```

### Initialize Project

Set up Flughafen in a new project:

```bash
# Interactive setup
flughafen init

# With options
flughafen init --output ./workflows --config
```

### Generate Types

Generate TypeScript definitions for GitHub Actions:

```bash
# Generate types for an action
flughafen generate-types actions/setup-node@v4

# Generate types for multiple actions
flughafen generate-types actions/setup-node@v4 actions/checkout@v4
```

## Configuration

Create a `flughafen.config.ts` file in your project root:

```typescript
import { defineConfig } from '@flughafen/cli';

export default defineConfig({
  // Input/output directories
  input: './workflows',
  output: './.github/workflows',

  // Validation options
  validation: {
    strict: false,
    typescript: true,
    structure: true,
    security: true,
    bestPractices: true
  },

  // Reverse engineering options
  reverse: {
    extractLocalActions: true,
    preserveComments: true
  }
});
```

## Examples

### Basic Workflow

```typescript
// workflows/ci.ts
import { createWorkflow } from 'flughafen';

export default createWorkflow()
  .name('CI Pipeline')
  .on('push', { branches: ['main'] })
  .job('test', (job) =>
    job
      .runsOn('ubuntu-latest')
      .step((step) => step.uses('actions/checkout@v4'))
      .step((step) => step.run('npm test'))
  );
```

Build it:

```bash
flughafen build workflows/ci.ts
```

### Convert Existing Workflow

```bash
# Convert YAML to TypeScript
flughafen reverse .github/workflows/ci.yml --output workflows

# Review the generated TypeScript
cat workflows/ci.ts

# Build it back to verify
flughafen build workflows/ci.ts

# Compare outputs
diff .github/workflows/ci.yml .github/workflows/ci.yml.generated
```

### Validate Before Commit

```bash
# Add to package.json
{
  "scripts": {
    "workflows:build": "flughafen build",
    "workflows:validate": "flughafen validate",
    "precommit": "pnpm workflows:validate && pnpm workflows:build"
  }
}
```

## Features

### ✅ Implemented

- **Build Command** - Convert TypeScript workflows to YAML
- **Validate Command** - Syntax and structure validation
- **Reverse Command** - Convert YAML workflows to TypeScript
  - Expression conversion (`${{ }}` → `expr()`)
  - Local action extraction
  - Batch processing
- **Init Command** - Project scaffolding
- **Generate Types** - Action type definitions

### 🚧 In Development

- **Advanced Validation** - Enhanced workflow analysis
  - Action schema validation
  - Reusable workflow validation
  - Security best practices
  - Performance analysis

## CLI Options

### Global Options

```bash
--help, -h        Show help
--version, -v     Show version
--verbose         Enable verbose logging
--quiet, -q       Suppress output
--config          Config file path (default: flughafen.config.ts)
```

### Build Options

```bash
--output, -o      Output directory (default: .github/workflows)
--watch, -w       Watch for changes
--dry-run         Preview without writing files
```

### Validate Options

```bash
--strict          Fail on warnings
--validate-only   Validate without generation
--fix             Auto-fix issues where possible
```

### Reverse Options

```bash
--output, -o              Output directory (default: ./workflows)
--extract-local-actions   Extract .github/actions to separate files
--local-actions-only      Only extract local actions
--preview                 Preview without writing files
--skip-local-actions      Skip local action extraction
--verbose                 Show detailed progress
--silent                  Suppress all output
```

## Development

```bash
# Install dependencies
pnpm install

# Build the CLI
pnpm build

# Test the CLI
./bin/flughafen --help

# Run tests
pnpm test

# Watch mode
pnpm dev
```

## Architecture

The CLI package provides a lightweight command-line interface that orchestrates the core Flughafen library:

```
@flughafen/cli/
├── src/
│   ├── cli.ts              # Main CLI application (Commander.js)
│   ├── commands/
│   │   ├── build.ts        # Build command
│   │   ├── validate.ts     # Validate command
│   │   ├── reverse.ts      # Reverse engineering command
│   │   ├── init.ts         # Init command
│   │   └── index.ts        # Command exports
│   └── utils/
│       ├── config.ts       # Config file loading
│       ├── spinner.ts      # Progress indicators
│       └── logger.ts       # Logging utilities
├── bin/
│   └── flughafen           # Executable entry point
└── dist/                   # Built output
```

## Troubleshooting

### Command Not Found

```bash
# Ensure package is installed
pnpm list @flughafen/cli

# Or use npx
npx @flughafen/cli build
```

### Config File Not Loading

```bash
# Specify config explicitly
flughafen build --config ./path/to/flughafen.config.ts

# Check config file syntax
node --loader tsx ./flughafen.config.ts
```

### Build Errors

```bash
# Enable verbose mode
flughafen build --verbose

# Check TypeScript compilation
tsc --noEmit
```

## Documentation

- 📖 **[CLI Guide](../../docs/cli.md)** - Complete CLI documentation
- 🔄 **[Reverse Engineering](../../docs/reverse-engineering-quick-start.md)** - YAML conversion guide
- 💡 **[Examples](../../examples/)** - Real-world examples
- ❓ **[FAQ](../../docs/faq.md)** - Frequently asked questions

## Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/jpwesselink/flughafen/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/jpwesselink/flughafen/discussions)
- 📖 **Documentation**: [docs/](../../docs/)

## License

MIT - See the [main project LICENSE](../../LICENSE.md) file.