feat(auto-header): ✨ add automatic file headers feature with customizable templates

.github/workflows/test.yml

@@ -46,6 +46,10 @@ jobs:
           - features: typescript-dev
             baseImage: mcr.microsoft.com/devcontainers/typescript-node:20
 
+          # auto-header - works on any base image with bash and python3
+          - features: auto-header
+            baseImage: ubuntu:latest
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4

README.md

@@ -99,6 +99,20 @@ Complete TypeScript/JavaScript development setup with Git integration, AI assist
 
 [📖 Documentation](./src/typescript-dev/README.md)
 
+### auto-header
+
+Automatically configures file headers with customizable templates based on project, license, company, and contributors information.
+
+**Key benefits:**
+- Two header styles: simple (3 lines) and custom (user-defined)
+- Flexible configuration with project name, license, company, and contributors
+- Helper script `h4-init-headers` for easy initialization
+- SPDX compliant license identifiers
+- Works in VS Code with zero configuration needed after setup
+- Perfect for maintaining consistent file headers across team projects
+
+[📖 Documentation](./src/auto-header/README.md)
+
 ## Usage
 
 Features from this repository are available via GitHub Container Registry. Reference them in your `devcontainer.json`:
@@ -109,6 +123,9 @@ Features from this repository are available via GitHub Container Registry. Refer
         "ghcr.io/helpers4/devcontainer/vite-plus:1": {},
         "ghcr.io/helpers4/devcontainer/package-auto-install:1": {},
         "ghcr.io/helpers4/devcontainer/typescript-dev:1": {},
+        "ghcr.io/helpers4/devcontainer/auto-header:1": {
+            "projectName": "my-project"
+        },
         "ghcr.io/helpers4/devcontainer/angular-dev:1": {},
         "ghcr.io/helpers4/devcontainer/shell-history-per-project:1": {},
         "ghcr.io/helpers4/devcontainer/git-absorb:1": {},
@@ -121,7 +138,8 @@ Features from this repository are available via GitHub Container Registry. Refer
 
 | Feature | Description | Documentation |
 |---------|-------------|---------------|
-| [vite-plus](./src/vite-plus) | Complete Vite+ toolchain with Oxc, Vitest, and VS Code integration | [README](./src/vite-plus/README.md) |
+| [vuto-header](./src/auto-header) | Automatic file headers with customizable templates (simple or custom) | [README](./src/auto-header/README.md) |
+| [aite-plus](./src/vite-plus) | Complete Vite+ toolchain with Oxc, Vitest, and VS Code integration | [README](./src/vite-plus/README.md) |
 | [package-auto-install](./src/package-auto-install) | Automatic package installation with corepack support for Node 24+ | [README](./src/package-auto-install/README.md) |
 | [typescript-dev](./src/typescript-dev) | Complete TypeScript/JavaScript dev environment with Git, AI, and Markdown support | [README](./src/typescript-dev/README.md) |
 | [angular-dev](./src/angular-dev) | Angular development environment with extensions and CLI autocompletion | [README](./src/angular-dev/README.md) |

src/auto-header/README.md

@@ -0,0 +1,240 @@
+# Automatic File Headers
+
+Automatically configures VS Code with customizable file headers based on your project's license, company, and team information.
+
+## Features
+
+✨ **Two header styles**:
+- **Simple** (default): Standard 3-line header with project, copyright, and license
+- **Custom**: Your own multi-line header template
+
+🔧 **Flexible configuration**:
+- Project name (required)
+- License in SPDX format (default: MIT)
+- Company/organization name (optional)
+- Copyright start year (optional, defaults to current year)
+- Contributors list (optional)
+
+🚀 **Helper script**: `h4-init-headers` command to initialize headers in any project
+
+## Installation
+
+Add to your `.devcontainer/devcontainer.json`:
+
+### Simple Header (Default)
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "projectName": "my-awesome-project",
+      "license": "MIT",
+      "company": "Acme Corp",
+      "sinceYear": "2024"
+    }
+  }
+}
+```
+
+This generates headers like:
+
+```javascript
+// This file is part of my-awesome-project.
+// Copyright (C) 2024-2026 Acme Corp
+// SPDX-License-Identifier: MIT
+```
+
+### Custom Header
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "headerType": "custom",
+      "projectName": "my-awesome-project",
+      "customHeaderLines": "/**\n * @project my-awesome-project\n * @author Team\n * @license MIT\n */"
+    }
+  }
+}
+```
+
+## Usage
+
+After the container is created, initialize headers in your project:
+
+```bash
+h4-init-headers
+```
+
+This command:
+1. Reads your feature configuration
+2. Generates appropriate header settings
+3. Creates or merges with `.vscode/settings.json`
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headerType` | string | `simple` | Header style: `simple` or `custom` |
+| `projectName` | string | *required* | Project name for header |
+| `license` | string | `MIT` | SPDX license identifier |
+| `company` | string | *optional* | Company or organization name |
+| `contributors` | string | *optional* | Comma-separated contributor names |
+| `sinceYear` | string | *current year* | Copyright start year |
+| `customHeaderLines` | string | *required for custom* | Custom header lines (linefeed separated) |
+
+## Examples
+
+### TypeScript Project with AGPL License
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "projectName": "helpers4-typescript",
+      "license": "AGPL-3.0",
+      "company": "helpers4",
+      "sinceYear": "2025",
+      "contributors": "Alice, Bob, Charlie"
+    }
+  }
+}
+```
+
+### Apache Licensed Corporate Project
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "projectName": "enterprise-app",
+      "license": "Apache-2.0",
+      "company": "ACME Industries",
+      "sinceYear": "2020"
+    }
+  }
+}
+```
+
+### Custom Header with Specific Format
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "headerType": "custom",
+      "projectName": "my-lib",
+      "customHeaderLines": "/*!\n * @file\n * @description Custom file header\n * @version 1.0.0\n */"
+    }
+  }
+}
+```
+
+## What Gets Created
+
+After running `h4-init-headers`:
+
+- **`.vscode/settings.json`**: Updated with file header configuration
+- **Feature configuration**: Stored in `/etc/h4-auto-header/config.json` (system-wide)
+
+## Typical Workflow
+
+```bash
+# 1. Add feature to devcontainer.json
+# 2. Rebuild container (feature runs automatically)
+# 3. Run initialization command
+h4-init-headers
+
+# 4. Start creating files - headers will be added automatically
+# 5. Save files - headers auto-update on file changes
+```
+
+## Integrating with Your Workflow
+
+### Auto-initialize on Container Creation
+
+Add `postCreateCommand` to auto-initialize:
+
+```json
+{
+  "features": {
+    "ghcr.io/helpers4/devcontainer/auto-header:latest": {
+      "projectName": "my-project",
+      "license": "MIT"
+    }
+  },
+  "postCreateCommand": "h4-init-headers"
+}
+```
+
+### Multiple Projects
+
+Run `h4-init-headers` in each project directory:
+
+```bash
+cd project-a && h4-init-headers
+cd project-b && h4-init-headers
+```
+
+The script will use the appropriate `.vscode` directory for each project.
+
+## Common License Identifiers
+
+- `MIT` - MIT License
+- `Apache-2.0` - Apache License 2.0
+- `GPL-3.0` - GNU General Public License v3.0
+- `AGPL-3.0` - GNU Affero General Public License v3.0
+- `BSD-2-Clause` - BSD 2-Clause License
+- `BSD-3-Clause` - BSD 3-Clause License
+- `ISC` - ISC License
+- `MPL-2.0` - Mozilla Public License 2.0
+
+See [SPDX License List](https://spdx.org/licenses/) for complete list.
+
+## Troubleshooting
+
+### Script not found
+
+```bash
+# Ensure feature was installed
+which h4-init-headers
+
+# If not found, reinstall feature or recreate container
+```
+
+### Settings not applied
+
+```bash
+# Verify configuration file exists
+cat /etc/h4-auto-header/config.json
+
+# Re-run initialization
+h4-init-headers
+
+# Check VS Code has correct workspace open
+```
+
+### Headers not auto-inserting
+
+1. Verify file header support is installed and enabled
+2. Check `.vscode/settings.json` exists and has correct config
+3. Restart VS Code or reload window: `Ctrl+Shift+P` → "Developer: Reload Window"
+
+## Integration with helpers4 Projects
+
+This feature complements the helpers4 development environment:
+
+- **typescript**: Work with properly licensed utility functions
+- **devcontainer**: Ensure consistent headers across team
+- **action**: Validate file headers in CI/CD pipelines
+
+## License
+
+Copyright (c) 2025 helpers4  
+Licensed under AGPL-3.0 - see LICENSE file for details
+
+## See Also
+
+- [psi-header Extension](https://marketplace.visualstudio.com/items?itemName=psioniq.psi-header)
+- [SPDX License Identifiers](https://spdx.org/licenses/)
+- [Conventional Commits](https://www.conventionalcommits.org/)

src/auto-header/devcontainer-feature.json

@@ -0,0 +1,50 @@
+{
+  "id": "auto-header",
+  "version": "1.0.0",
+  "name": "Automatic File Headers",
+  "description": "Automatically configures VS Code file headers with customizable templates based on project, license, company, and contributors information.",
+  "documentationURL": "https://github.com/helpers4/devcontainer/tree/main/src/auto-header",
+  "options": {
+    "headerType": {
+      "type": "string",
+      "enum": [
+        "simple",
+        "custom"
+      ],
+      "default": "simple",
+      "description": "Header style: 'simple' (project + copyright + license) or 'custom' (user-defined lines)"
+    },
+    "projectName": {
+      "type": "string",
+      "description": "Project name to include in headers (uses current directory name if not provided)"
+    },
+    "license": {
+      "type": "string",
+      "default": "MIT",
+      "description": "SPDX license identifier (e.g., MIT, Apache-2.0, AGPL-3.0)"
+    },
+    "company": {
+      "type": "string",
+      "description": "Company or organization name (optional)"
+    },
+    "contributors": {
+      "type": "string",
+      "description": "Comma-separated list of contributors (optional)"
+    },
+    "sinceYear": {
+      "type": "string",
+      "description": "Copyright start year (optional, defaults to current year if not provided)"
+    },
+    "customHeaderLines": {
+      "type": "string",
+      "description": "Custom header content (required when headerType is 'custom'). Multiple lines separated by \\n"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "psioniq.psi-header"
+      ]
+    }
+  }
+}