Skip to content

Commit d964125

Browse files
baxyzbaxyz
committed
feat(auto-header): ✨ add automatic file headers feature with customizable templates
1 parent d5f7be0 commit d964125

6 files changed

Lines changed: 670 additions & 1 deletion

File tree

‎.github/workflows/test.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ jobs:
4646
- features: typescript-dev
4747
baseImage: mcr.microsoft.com/devcontainers/typescript-node:20
4848

49+
# auto-header - works on any base image with bash and python3
50+
- features: auto-header
51+
baseImage: ubuntu:latest
52+
4953
steps:
5054
- name: Checkout
5155
uses: actions/checkout@v4

‎README.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,20 @@ Complete TypeScript/JavaScript development setup with Git integration, AI assist
9999

100100
[📖 Documentation](./src/typescript-dev/README.md)
101101

102+
### auto-header
103+
104+
Automatically configures file headers with customizable templates based on project, license, company, and contributors information.
105+
106+
**Key benefits:**
107+
- Two header styles: simple (3 lines) and custom (user-defined)
108+
- Flexible configuration with project name, license, company, and contributors
109+
- Helper script `h4-init-headers` for easy initialization
110+
- SPDX compliant license identifiers
111+
- Works in VS Code with zero configuration needed after setup
112+
- Perfect for maintaining consistent file headers across team projects
113+
114+
[📖 Documentation](./src/auto-header/README.md)
115+
102116
## Usage
103117

104118
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
109123
"ghcr.io/helpers4/devcontainer/vite-plus:1": {},
110124
"ghcr.io/helpers4/devcontainer/package-auto-install:1": {},
111125
"ghcr.io/helpers4/devcontainer/typescript-dev:1": {},
126+
"ghcr.io/helpers4/devcontainer/auto-header:1": {
127+
"projectName": "my-project"
128+
},
112129
"ghcr.io/helpers4/devcontainer/angular-dev:1": {},
113130
"ghcr.io/helpers4/devcontainer/shell-history-per-project:1": {},
114131
"ghcr.io/helpers4/devcontainer/git-absorb:1": {},
@@ -121,7 +138,8 @@ Features from this repository are available via GitHub Container Registry. Refer
121138

122139
| Feature | Description | Documentation |
123140
|---------|-------------|---------------|
124-
| [vite-plus](./src/vite-plus) | Complete Vite+ toolchain with Oxc, Vitest, and VS Code integration | [README](./src/vite-plus/README.md) |
141+
| [vuto-header](./src/auto-header) | Automatic file headers with customizable templates (simple or custom) | [README](./src/auto-header/README.md) |
142+
| [aite-plus](./src/vite-plus) | Complete Vite+ toolchain with Oxc, Vitest, and VS Code integration | [README](./src/vite-plus/README.md) |
125143
| [package-auto-install](./src/package-auto-install) | Automatic package installation with corepack support for Node 24+ | [README](./src/package-auto-install/README.md) |
126144
| [typescript-dev](./src/typescript-dev) | Complete TypeScript/JavaScript dev environment with Git, AI, and Markdown support | [README](./src/typescript-dev/README.md) |
127145
| [angular-dev](./src/angular-dev) | Angular development environment with extensions and CLI autocompletion | [README](./src/angular-dev/README.md) |

‎src/auto-header/README.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Automatic File Headers
2+
3+
Automatically configures VS Code with customizable file headers based on your project's license, company, and team information.
4+
5+
## Features
6+
7+
✨ **Two header styles**:
8+
- **Simple** (default): Standard 3-line header with project, copyright, and license
9+
- **Custom**: Your own multi-line header template
10+
11+
🔧 **Flexible configuration**:
12+
- Project name (required)
13+
- License in SPDX format (default: MIT)
14+
- Company/organization name (optional)
15+
- Copyright start year (optional, defaults to current year)
16+
- Contributors list (optional)
17+
18+
🚀 **Helper script**: `h4-init-headers` command to initialize headers in any project
19+
20+
## Installation
21+
22+
Add to your `.devcontainer/devcontainer.json`:
23+
24+
### Simple Header (Default)
25+
26+
```json
27+
{
28+
"features": {
29+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
30+
"projectName": "my-awesome-project",
31+
"license": "MIT",
32+
"company": "Acme Corp",
33+
"sinceYear": "2024"
34+
}
35+
}
36+
}
37+
```
38+
39+
This generates headers like:
40+
41+
```javascript
42+
// This file is part of my-awesome-project.
43+
// Copyright (C) 2024-2026 Acme Corp
44+
// SPDX-License-Identifier: MIT
45+
```
46+
47+
### Custom Header
48+
49+
```json
50+
{
51+
"features": {
52+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
53+
"headerType": "custom",
54+
"projectName": "my-awesome-project",
55+
"customHeaderLines": "/**\n * @project my-awesome-project\n * @author Team\n * @license MIT\n */"
56+
}
57+
}
58+
}
59+
```
60+
61+
## Usage
62+
63+
After the container is created, initialize headers in your project:
64+
65+
```bash
66+
h4-init-headers
67+
```
68+
69+
This command:
70+
1. Reads your feature configuration
71+
2. Generates appropriate header settings
72+
3. Creates or merges with `.vscode/settings.json`
73+
74+
## Configuration Options
75+
76+
| Option | Type | Default | Description |
77+
|--------|------|---------|-------------|
78+
| `headerType` | string | `simple` | Header style: `simple` or `custom` |
79+
| `projectName` | string | *required* | Project name for header |
80+
| `license` | string | `MIT` | SPDX license identifier |
81+
| `company` | string | *optional* | Company or organization name |
82+
| `contributors` | string | *optional* | Comma-separated contributor names |
83+
| `sinceYear` | string | *current year* | Copyright start year |
84+
| `customHeaderLines` | string | *required for custom* | Custom header lines (linefeed separated) |
85+
86+
## Examples
87+
88+
### TypeScript Project with AGPL License
89+
90+
```json
91+
{
92+
"features": {
93+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
94+
"projectName": "helpers4-typescript",
95+
"license": "AGPL-3.0",
96+
"company": "helpers4",
97+
"sinceYear": "2025",
98+
"contributors": "Alice, Bob, Charlie"
99+
}
100+
}
101+
}
102+
```
103+
104+
### Apache Licensed Corporate Project
105+
106+
```json
107+
{
108+
"features": {
109+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
110+
"projectName": "enterprise-app",
111+
"license": "Apache-2.0",
112+
"company": "ACME Industries",
113+
"sinceYear": "2020"
114+
}
115+
}
116+
}
117+
```
118+
119+
### Custom Header with Specific Format
120+
121+
```json
122+
{
123+
"features": {
124+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
125+
"headerType": "custom",
126+
"projectName": "my-lib",
127+
"customHeaderLines": "/*!\n * @file\n * @description Custom file header\n * @version 1.0.0\n */"
128+
}
129+
}
130+
}
131+
```
132+
133+
## What Gets Created
134+
135+
After running `h4-init-headers`:
136+
137+
- **`.vscode/settings.json`**: Updated with file header configuration
138+
- **Feature configuration**: Stored in `/etc/h4-auto-header/config.json` (system-wide)
139+
140+
## Typical Workflow
141+
142+
```bash
143+
# 1. Add feature to devcontainer.json
144+
# 2. Rebuild container (feature runs automatically)
145+
# 3. Run initialization command
146+
h4-init-headers
147+
148+
# 4. Start creating files - headers will be added automatically
149+
# 5. Save files - headers auto-update on file changes
150+
```
151+
152+
## Integrating with Your Workflow
153+
154+
### Auto-initialize on Container Creation
155+
156+
Add `postCreateCommand` to auto-initialize:
157+
158+
```json
159+
{
160+
"features": {
161+
"ghcr.io/helpers4/devcontainer/auto-header:latest": {
162+
"projectName": "my-project",
163+
"license": "MIT"
164+
}
165+
},
166+
"postCreateCommand": "h4-init-headers"
167+
}
168+
```
169+
170+
### Multiple Projects
171+
172+
Run `h4-init-headers` in each project directory:
173+
174+
```bash
175+
cd project-a && h4-init-headers
176+
cd project-b && h4-init-headers
177+
```
178+
179+
The script will use the appropriate `.vscode` directory for each project.
180+
181+
## Common License Identifiers
182+
183+
- `MIT` - MIT License
184+
- `Apache-2.0` - Apache License 2.0
185+
- `GPL-3.0` - GNU General Public License v3.0
186+
- `AGPL-3.0` - GNU Affero General Public License v3.0
187+
- `BSD-2-Clause` - BSD 2-Clause License
188+
- `BSD-3-Clause` - BSD 3-Clause License
189+
- `ISC` - ISC License
190+
- `MPL-2.0` - Mozilla Public License 2.0
191+
192+
See [SPDX License List](https://spdx.org/licenses/) for complete list.
193+
194+
## Troubleshooting
195+
196+
### Script not found
197+
198+
```bash
199+
# Ensure feature was installed
200+
which h4-init-headers
201+
202+
# If not found, reinstall feature or recreate container
203+
```
204+
205+
### Settings not applied
206+
207+
```bash
208+
# Verify configuration file exists
209+
cat /etc/h4-auto-header/config.json
210+
211+
# Re-run initialization
212+
h4-init-headers
213+
214+
# Check VS Code has correct workspace open
215+
```
216+
217+
### Headers not auto-inserting
218+
219+
1. Verify file header support is installed and enabled
220+
2. Check `.vscode/settings.json` exists and has correct config
221+
3. Restart VS Code or reload window: `Ctrl+Shift+P` → "Developer: Reload Window"
222+
223+
## Integration with helpers4 Projects
224+
225+
This feature complements the helpers4 development environment:
226+
227+
- **typescript**: Work with properly licensed utility functions
228+
- **devcontainer**: Ensure consistent headers across team
229+
- **action**: Validate file headers in CI/CD pipelines
230+
231+
## License
232+
233+
Copyright (c) 2025 helpers4
234+
Licensed under AGPL-3.0 - see LICENSE file for details
235+
236+
## See Also
237+
238+
- [psi-header Extension](https://marketplace.visualstudio.com/items?itemName=psioniq.psi-header)
239+
- [SPDX License Identifiers](https://spdx.org/licenses/)
240+
- [Conventional Commits](https://www.conventionalcommits.org/)

‎src/auto-header/devcontainer-feature.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"id": "auto-header",
3+
"version": "1.0.0",
4+
"name": "Automatic File Headers",
5+
"description": "Automatically configures VS Code file headers with customizable templates based on project, license, company, and contributors information.",
6+
"documentationURL": "https://github.com/helpers4/devcontainer/tree/main/src/auto-header",
7+
"options": {
8+
"headerType": {
9+
"type": "string",
10+
"enum": [
11+
"simple",
12+
"custom"
13+
],
14+
"default": "simple",
15+
"description": "Header style: 'simple' (project + copyright + license) or 'custom' (user-defined lines)"
16+
},
17+
"projectName": {
18+
"type": "string",
19+
"description": "Project name to include in headers (uses current directory name if not provided)"
20+
},
21+
"license": {
22+
"type": "string",
23+
"default": "MIT",
24+
"description": "SPDX license identifier (e.g., MIT, Apache-2.0, AGPL-3.0)"
25+
},
26+
"company": {
27+
"type": "string",
28+
"description": "Company or organization name (optional)"
29+
},
30+
"contributors": {
31+
"type": "string",
32+
"description": "Comma-separated list of contributors (optional)"
33+
},
34+
"sinceYear": {
35+
"type": "string",
36+
"description": "Copyright start year (optional, defaults to current year if not provided)"
37+
},
38+
"customHeaderLines": {
39+
"type": "string",
40+
"description": "Custom header content (required when headerType is 'custom'). Multiple lines separated by \\n"
41+
}
42+
},
43+
"customizations": {
44+
"vscode": {
45+
"extensions": [
46+
"psioniq.psi-header"
47+
]
48+
}
49+
}
50+
}

0 commit comments

Comments
 (0)