ai-code-to-project-files/readme.md

A CLI tool to convert AI code responses with multiple file sections into organized project files

# AI Code to Project Files

A Node.js CLI tool and module that converts AI code responses containing multiple file sections into organized project files. Perfect for when AI assistants provide code across multiple files and you want to quickly generate the actual file structure.

## Features

- ✅ Parse AI code responses with multiple file sections
- ✅ Generate organized project structures
- ✅ CLI tool for command-line usage
- ✅ Programmatic API for Node.js projects
- ✅ Automatic directory creation
- ✅ File path validation
- ✅ Cross-platform compatibility

## Installation

### Global Installation (CLI Usage)
```bash
npm install -g ai-code-to-project-files
```

### Local Installation (Module Usage)
```bash
npm install ai-code-to-project-files
```

### Development Installation
```bash
git clone <repository-url>
cd ai-code-to-project-files
npm install
npm link  # For global CLI access during development
```

## CLI Usage

After global installation, use the `ai-code-to-files` command:

```bash
# Basic usage
ai-code-to-files response.txt

# Specify output directory
ai-code-to-files response.txt ./my-project

# Full path example
ai-code-to-files /path/to/ai-response.txt ./output-folder
```

### CLI Options
```bash
ai-code-to-files --help     # Show help
ai-code-to-files --version  # Show version
```

## Module Usage (Programmatic API)

```javascript
const { generateFromFile, generateFromContent } = require('ai-code-to-project-files');

// Generate from file
async function example1() {
  const result = await generateFromFile('response.txt', './output');
  if (result.success) {
    console.log(`Generated ${result.files} files successfully`);
  } else {
    console.error('Error:', result.error);
  }
}

// Generate from content string
async function example2() {
  const content = `
# src/index.js
console.log('Hello World');

# package.json
{
  "name": "my-app",
  "version": "1.0.0"
}
`;
  
  const result = await generateFromContent(content, './my-project');
  if (result.success) {
    console.log('Project generated successfully');
  }
}
```

## Input Format

Your input file should contain AI responses with file sections formatted like this:

```
# src/components/Header.js
import React from 'react';

export default function Header() {
  return <h1>My App</h1>;
}

# src/styles/main.css
body {
  font-family: Arial, sans-serif;
  margin: 0;
  padding: 20px;
}

# package.json
{
  "name": "my-react-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}
```

## API Reference

### `generateFromFile(inputFilePath, outputDir)`
Generates project structure from a text file.

**Parameters:**
- `inputFilePath` (string): Path to the input .txt file
- `outputDir` (string, optional): Output directory (default: './generated_project')

**Returns:** Promise<Object>
```javascript
{
  success: boolean,
  message?: string,
  files?: number,
  error?: string
}
```

### `generateFromContent(content, outputDir)`
Generates project structure from a content string.

**Parameters:**
- `content` (string): The artifact content as string
- `outputDir` (string, optional): Output directory (default: './generated_project')

**Returns:** Promise<Object> (same as above)

### `parseArtifactContent(artifactContent)`
Parses artifact content and extracts file information.

**Parameters:**
- `artifactContent` (string): The content to parse

**Returns:** Promise<Array> of file objects with `path` and `content` properties

### `createFileStructure(files, baseDir)`
Creates directories and files from parsed data.

**Parameters:**
- `files` (Array): Array of file objects
- `baseDir` (string): Base directory to create files in

**Returns:** Promise<void>

## Error Handling

The module provides comprehensive error handling:

- Invalid file paths are automatically skipped with warnings
- Missing or invalid input files throw descriptive errors
- Directory creation failures are caught and reported
- File writing errors include full context

## Requirements

- Node.js >= 12.0.0
- File system write permissions for output directory

## Examples

### Example 1: Basic CLI Usage
```bash
# Save AI response to file
echo "# src/app.js
console.log('Hello World');

# README.md
# My Project
This is a sample project." > ai-response.txt

# Generate project
ai-code-to-files ai-response.txt
```

### Example 2: Programmatic Usage
```javascript
const { generateFromContent } = require('ai-code-to-project-files');

async function createProject() {
  const aiResponse = `
# backend/server.js
const express = require('express');
const app = express();
app.listen(3000);

# frontend/index.html
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body><h1>Welcome</h1></body>
</html>

# .gitignore
node_modules/
.env
`;

  const result = await generateFromContent(aiResponse, './full-stack-app');
  
  if (result.success) {
    console.log('✅ Full-stack project created!');
  } else {
    console.error('❌ Error:', result.error);
  }
}

createProject();
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see LICENSE file for details.

## Changelog

### v1.0.0
- Initial release
- CLI tool with global installation
- Programmatic API
- File path validation
- Cross-platform support