relspecgo/vscode-extension/relspec-template-editor/README.md

# RelSpec Template Editor for VS Code

Visual editor and tooling for RelSpec PostgreSQL migration templates.

## Features

### 1. Template Preview
- **Command**: `RelSpec: Preview Template`
- **Shortcut**: Click the preview icon in the editor title bar
- Preview your templates with sample data
- Side-by-side view of template, data, and rendered SQL

### 2. Syntax Validation
- **Command**: `RelSpec: Validate Template`
- Automatic validation on save (configurable)
- Highlights syntax errors inline
- Checks for unclosed template tags

### 3. IntelliSense
- Auto-completion for template functions
- Function signatures and documentation on hover
- Keyword completions (`if`, `range`, `template`, etc.)

### 4. Template Scaffolding
- **Command**: `RelSpec: New Template`
- Quick scaffolding for common template types:
  - DDL operations
  - Constraints
  - Indexes
  - Audit trails
  - Reusable fragments

### 5. Function Library
- **Command**: `RelSpec: List Available Functions`
- Browse all available template functions
- See examples and documentation
- Quick reference for template development

## Installation

### From Source

1. Clone the RelSpec repository
2. Navigate to the extension directory:
   ```bash
   cd vscode-extension
   ```
3. Install dependencies:
   ```bash
   npm install
   ```
4. Compile the extension:
   ```bash
   npm run compile
   ```
5. Open in VS Code:
   ```bash
   code .
   ```
6. Press `F5` to launch the extension in a new window

### From VSIX (when published)

```bash
code --install-extension relspec-template-editor-0.1.0.vsix
```

## Usage

### Opening Templates

1. Open your RelSpec project in VS Code
2. Navigate to `pkg/writers/pgsql/templates/`
3. Open any `.tmpl` file
4. The extension will automatically activate

### Previewing Templates

1. Open a template file
2. Click the preview icon in the editor title bar OR
3. Run command: `RelSpec: Preview Template` (Ctrl+Shift+P)
4. The preview pane will show:
   - Your template source
   - Sample data (configurable)
   - Rendered SQL output

### Configuring Sample Data

Set custom sample data for preview in settings:

```json
{
  "relspec.previewSampleData": {
    "SchemaName": "public",
    "TableName": "users",
    "ColumnName": "email",
    "Columns": [
      {"Name": "id", "Type": "integer", "NotNull": true},
      {"Name": "email", "Type": "text"}
    ]
  }
}
```

### Creating New Templates

1. Run command: `RelSpec: New Template`
2. Select template type
3. Enter template name
4. The extension creates a scaffolded template
5. Edit and customize

### Using IntelliSense

Type `{{` to trigger auto-completion:

```gotmpl
{{upper  // Shows function signature and documentation
{{.     // Shows available fields from data structure
```

Hover over function names to see:
- Function signature
- Description
- Usage examples

## Configuration

Available settings:

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `relspec.templatePath` | string | `pkg/writers/pgsql/templates` | Path to template directory |
| `relspec.autoValidate` | boolean | `true` | Validate templates on save |
| `relspec.showDataStructures` | boolean | `true` | Show data structure hints in preview |
| `relspec.previewSampleData` | object | `{}` | Sample JSON data for preview |

## Keyboard Shortcuts

| Command | Shortcut | Description |
|---------|----------|-------------|
| Preview Template | N/A | Click preview icon in title bar |
| Validate Template | N/A | Use command palette |
| New Template | N/A | Use command palette |

## Template Functions Reference

The extension provides IntelliSense for all RelSpec template functions:

### String Manipulation
- `upper` - Convert to uppercase
- `lower` - Convert to lowercase
- `title` - Title case
- `snake_case` - Convert to snake_case
- `camelCase` - Convert to camelCase

### SQL Formatting
- `indent` - Indent text
- `quote` - Quote for SQL
- `escape` - Escape special characters
- `safe_identifier` - Make safe SQL identifier

### Type Conversion
- `goTypeToSQL` - Go type → SQL type
- `sqlTypeToGo` - SQL type → Go type
- `isNumeric` - Check if numeric type
- `isText` - Check if text type

### Collection Helpers
- `first` - First element
- `last` - Last element
- `filter` - Filter elements
- `mapFunc` - Map function
- `join_with` - Join with separator
- `join` - Join strings

See full documentation: [Template Functions](../pkg/writers/pgsql/TEMPLATE_FUNCTIONS.md)

## Code Snippets

The extension includes snippets for common patterns:

| Prefix | Description |
|--------|-------------|
| `tmpl-define` | Define a new template |
| `tmpl-template` | Use a template |
| `tmpl-block` | Define a block |
| `tmpl-if` | If statement |
| `tmpl-range` | Range loop |
| `tmpl-with` | With statement |

## Development

### Building

```bash
npm run compile
```

### Watching

```bash
npm run watch
```

### Linting

```bash
npm run lint
```

### Testing

```bash
npm test
```

## Troubleshooting

### Extension Not Activating

**Problem**: Extension doesn't activate when opening .tmpl files

**Solution**:
1. Check that file has `.tmpl` extension
2. Reload VS Code window (Ctrl+Shift+P → "Reload Window")
3. Check extension is enabled in Extensions panel

### Preview Not Working

**Problem**: Preview shows error or doesn't update

**Solution**:
1. Ensure RelSpec binary is in PATH
2. Check template syntax is valid
3. Verify sample data is valid JSON

### IntelliSense Not Working

**Problem**: Auto-completion doesn't trigger

**Solution**:
1. Type `{{` to trigger
2. Check language mode is set to "Go Template"
3. Reload window

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

Same as RelSpec project license.

## Links

- [RelSpec Documentation](../README.md)
- [Template Documentation](../pkg/writers/pgsql/TEMPLATES.md)
- [Template Inheritance](../pkg/writers/pgsql/TEMPLATE_INHERITANCE.md)
- [Issue Tracker](https://github.com/yourorg/relspec/issues)

## Changelog

### 0.1.0 (Initial Release)
- Template preview with sample data
- Syntax validation
- IntelliSense for functions
- Template scaffolding
- Function library browser