🔧 Automatic file:// protocol handling and devcontainer improvements (#68)

## 🎯 Overview

This PR introduces automatic file protocol handling and improves the
development container configuration for better developer experience.

## ✨ What's Changed

### 🔧 File Protocol Enhancement
- **Automatic `file://` prepending** - YAML files without protocol
automatically get `file://` prefix
- **Simplified usage** - Users can now specify YAML files directly
without remembering protocol syntax
- **Backward compatibility** - Existing `file://` prefixed paths
continue to work unchanged

### 🐳 DevContainer Improvements  
- **Streamlined Python setup** - Commented out redundant Python feature
(base image already includes Python)
- **OpenAI API integration** - Added environment variable for AI-powered
features
- **Better development experience** - Optimized container configuration
for faster startup

## 📖 Usage Examples

### Before (Manual Protocol)
```bash
# Users had to remember the file:// protocol
struct generate file://my-config.yaml ./output
```

### After (Automatic Protocol)
```bash
# Protocol is automatically added for .yaml files
struct generate my-config.yaml ./output

# Still works with explicit protocol
struct generate file://my-config.yaml ./output
```

## 🔧 Technical Implementation

### File Protocol Logic
- Checks if file ends with `.yaml` and doesn't start with `file://`
- Automatically prepends `file://` protocol when conditions are met
- Maintains existing behavior for all other cases

### DevContainer Optimizations
- Removed redundant Python feature installation
- Added OpenAI API key environment variable for AI integrations
- Preserved all existing extensions and settings

## ✅ Benefits

### For End Users
- **Simplified commands** - No need to remember file protocol syntax
- **Reduced errors** - Automatic protocol handling prevents common
mistakes
- **Consistent experience** - Works the same way regardless of protocol
specification

### For Developers
- **Faster container startup** - Removed redundant Python installation
- **AI integration ready** - OpenAI API key environment configured
- **Better DX** - Streamlined development environment

## 🧪 Testing

- ✅ Verified automatic protocol prepending works correctly
- ✅ Confirmed backward compatibility with explicit protocols
- ✅ Tested devcontainer builds successfully with new configuration
- ✅ Validated all existing functionality remains intact

## 📁 Files Modified

- **`struct_module/commands/generate.py`** - Added automatic file
protocol handling
- **`.devcontainer/devcontainer.json`** - Optimized container
configuration

## 🔗 Compatibility

- **✅ Backward Compatible** - All existing commands continue to work
- **✅ Protocol Agnostic** - Supports both explicit and automatic
protocol handling
- **✅ Environment Ready** - Enhanced development container setup

---

This enhancement improves user experience by removing the need to
manually specify file protocols while maintaining full backward
compatibility and improving the development environment.

Author: httpdss

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
   "name": "Struct devcontainer",
   "image": "mcr.microsoft.com/devcontainers/python:3",
   "features": {
-    "ghcr.io/devcontainers/features/python:1": {},
+    // "ghcr.io/devcontainers/features/python:1": {},
     "ghcr.io/gvatsal60/dev-container-features/pre-commit:1": {}
   },
   "postCreateCommand": "bash ./scripts/devcontainer_start.sh",
@@ -30,5 +30,9 @@
   "mounts": [
     "type=bind,source=${localWorkspaceFolder},target=/work",
     "type=bind,source=/home/${localEnv:USER}/.ssh,target=/home/vscode/.ssh"
-  ]
+  ],
+  // environment variables to be set in the container
+  "remoteEnv": {
+    "OPENAI_API_KEY": "set-key-here"
+  }
 }

docs/configuration.md

@@ -10,6 +10,8 @@ When defining your project structure in the YAML configuration file, you can use
 - **content**: Define the content of the file directly in the YAML configuration.
 - **file**: Specify a local or remote file to include. Supported protocols include `file://`, `http://`, `https://`, `github://`, `githubhttps://`, `githubssh://`, `s3://`, and `gs://`.
 
+  > **Note**: For local `.yaml` files, the `file://` protocol is automatically added if not specified.
+
 Example:
 
 ```yaml

docs/development.md

@@ -178,7 +178,7 @@ pytest tests/integration/
 ### Enable Debug Logging
 
 ```sh
-struct --log=DEBUG generate file://my-config.yaml ./output
+struct --log=DEBUG generate my-config.yaml ./output
 ```
 
 ### Use Python Debugger

docs/file-handling.md

@@ -138,15 +138,17 @@ Control how STRUCT handles existing files with the `--file-strategy` option:
 
 ```sh
 # Skip existing files
-struct generate --file-strategy=skip file://my-config.yaml ./output
+struct generate --file-strategy=skip my-config.yaml ./output
 
 # Backup existing files
-struct generate --file-strategy=backup --backup=/tmp/backup file://my-config.yaml ./output
+struct generate --file-strategy=backup --backup=/tmp/backup my-config.yaml ./output
 
 # Rename existing files
-struct generate --file-strategy=rename file://my-config.yaml ./output
+struct generate --file-strategy=rename my-config.yaml ./output
 ```
 
+> **Note**: The `file://` protocol is automatically added for `.yaml` files, so these examples work with or without the explicit protocol.
+
 ## Advanced Examples
 
 ### Conditional File Creation

docs/mappings.md

@@ -146,6 +146,8 @@ This approach allows you to pass specific mapping values as variables to nested
 Use the `--mappings-file` argument with the `generate` command:
 
 ```sh
+# Both commands work identically - file:// is automatically added for .yaml files
+struct generate --mappings-file ./mymap.yaml my-struct.yaml .
 struct generate --mappings-file ./mymap.yaml file://my-struct.yaml .
 ```
 
@@ -157,7 +159,7 @@ You can specify multiple mappings files that will be merged in order:
 struct generate \
   --mappings-file ./common-mappings.yaml \
   --mappings-file ./env-specific-mappings.yaml \
-  file://my-struct.yaml .
+  my-struct.yaml .
 ```
 
 **Merging behavior:**
@@ -173,7 +175,7 @@ struct generate \
 struct generate \
   --mappings-file ./mappings/common.yaml \
   --mappings-file ./mappings/${ENVIRONMENT}.yaml \
-  file://infrastructure.yaml \
+  infrastructure.yaml \
   ./output
 ```
 

docs/quickstart.md

@@ -40,9 +40,11 @@ mkdir example
 cd example/
 touch structure.yaml
 vim structure.yaml # copy the content from the example folder
-struct generate file://structure.yaml .
+struct generate structure.yaml .
 ```
 
+> **Note**: The `file://` protocol is automatically added for `.yaml` files, so `structure.yaml` and `file://structure.yaml` work identically.
+
 ## First Example
 
 After installing STRUCT, try this simple example:

docs/usage.md

@@ -24,6 +24,16 @@ struct -h
 struct generate terraform-module ./my-terraform-module
 ```
 
+### YAML File Usage
+
+For local YAML configuration files, the `file://` protocol is automatically added:
+
+```sh
+# Both of these work identically
+struct generate my-config.yaml ./output
+struct generate file://my-config.yaml ./output
+```
+
 ### Complete Example
 
 ```sh

struct_module/commands/generate.py

@@ -62,6 +62,9 @@ def _run_hooks(self, hooks, hook_type="pre"):  # helper for running hooks
     return True
 
   def _load_yaml_config(self, structure_definition, structures_path):
+    if structure_definition.endswith(".yaml") and not structure_definition.startswith("file://"):
+      structure_definition = f"file://{structure_definition}"
+
     if structure_definition.startswith("file://") and structure_definition.endswith(".yaml"):
       with open(structure_definition[7:], 'r') as f:
         return yaml.safe_load(f)