Skip to content

Commit b409823

Browse files
jakejarvisjakejarvis
authored
feat: allow environment variable overrides of default behaviors (#182)
1 parent d14ea4d commit b409823

15 files changed

Lines changed: 1288 additions & 188 deletions

File tree

‎.github/workflows/bump-hugo-version.yml‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,13 @@ jobs:
1616
name: Bump to latest Hugo version
1717
runs-on: ubuntu-latest
1818
steps:
19-
- uses: actions/checkout@v6
19+
- name: Checkout
20+
uses: actions/checkout@v6
2021
with:
2122
fetch-depth: 0
2223

23-
- uses: actions/setup-node@v6
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v6
2426
with:
2527
node-version: "24"
2628

@@ -64,7 +66,7 @@ jobs:
6466
GH_TOKEN: ${{ github.token }}
6567
run: |
6668
LATEST="${{ steps.hugo.outputs.version }}"
67-
BRANCH_NAME="hugo-v${LATEST}"
69+
BRANCH_NAME="autobump-hugo-v${LATEST}"
6870
6971
# Check if a PR for this version already exists
7072
EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --json number --jq '.[0].number // empty')
@@ -87,7 +89,7 @@ jobs:
8789
if: steps.check.outputs.needs_update == 'true' && steps.pr_check.outputs.pr_exists == 'false'
8890
run: |
8991
LATEST="${{ steps.hugo.outputs.version }}"
90-
BRANCH_NAME="hugo-v${LATEST}"
92+
BRANCH_NAME="autobump-hugo-v${LATEST}"
9193
9294
# Create new branch
9395
git checkout -b "$BRANCH_NAME"
@@ -103,7 +105,7 @@ jobs:
103105
if: steps.check.outputs.needs_update == 'true' && steps.pr_check.outputs.pr_exists == 'false'
104106
run: |
105107
LATEST="${{ steps.hugo.outputs.version }}"
106-
BRANCH_NAME="hugo-v${LATEST}"
108+
BRANCH_NAME="autobump-hugo-v${LATEST}"
107109
108110
git commit -m "chore: bump to Hugo v${LATEST}"
109111
git push origin "$BRANCH_NAME"
@@ -114,7 +116,7 @@ jobs:
114116
GH_TOKEN: ${{ github.token }}
115117
run: |
116118
LATEST="${{ steps.hugo.outputs.version }}"
117-
BRANCH_NAME="hugo-v${LATEST}"
119+
BRANCH_NAME="autobump-hugo-v${LATEST}"
118120
119121
gh pr create \
120122
--title "chore: bump to Hugo v${LATEST}" \

‎.github/workflows/publish.yml‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,34 @@ jobs:
1414
name: Publish to NPM
1515
runs-on: ubuntu-latest
1616
steps:
17-
- uses: actions/checkout@v6
18-
- uses: actions/setup-node@v6
17+
- name: Checkout
18+
uses: actions/checkout@v6
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v6
1924
with:
2025
node-version: "24"
2126
registry-url: "https://registry.npmjs.org"
27+
28+
- name: Setup Bun
29+
uses: oven-sh/setup-bun@v2
30+
2231
- name: Install dependencies
2332
run: npm install -g npm@latest && npm ci
33+
2434
- name: Generate types
2535
run: npm run generate-types
36+
2637
- name: Lint
2738
run: npm run lint
39+
2840
- name: Type check
2941
run: npm run typecheck
42+
3043
- name: Build
3144
run: npm run build
45+
3246
- name: Publish
3347
run: npm publish

‎.github/workflows/test.yml‎

Lines changed: 78 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,33 @@ jobs:
1919
matrix:
2020
node: ["20", "22", "24"]
2121
steps:
22-
- uses: actions/checkout@v6
23-
- uses: actions/setup-node@v6
22+
- name: Checkout
23+
uses: actions/checkout@v6
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v6
2427
with:
2528
node-version: ${{ matrix.node }}
2629
cache: "npm"
30+
31+
- name: Setup Bun
32+
uses: oven-sh/setup-bun@v2
33+
2734
- name: Install dependencies
2835
run: npm ci
36+
2937
- name: Generate types
3038
run: npm run generate-types
39+
3140
- name: Lint
3241
run: npm run lint
42+
3343
- name: Type check
3444
run: npm run typecheck
45+
3546
- name: Build
3647
run: npm run build
48+
3749
- name: Run unit tests
3850
run: npm run test:unit
3951

@@ -48,17 +60,27 @@ jobs:
4860
os: [ubuntu-latest, macos-latest, windows-latest]
4961
node: ["20", "22", "24"]
5062
steps:
51-
- uses: actions/checkout@v6
52-
- uses: actions/setup-node@v6
63+
- name: Checkout
64+
uses: actions/checkout@v6
65+
66+
- name: Setup Node.js
67+
uses: actions/setup-node@v6
5368
with:
5469
node-version: ${{ matrix.node }}
5570
cache: "npm"
71+
72+
- name: Setup Bun
73+
uses: oven-sh/setup-bun@v2
74+
5675
- name: Install dependencies
5776
run: npm ci
77+
5878
- name: Generate types
5979
run: npm run generate-types
80+
6081
- name: Build
6182
run: npm run build
83+
6284
- name: Run integration tests
6385
run: npm run test:integration
6486

@@ -72,17 +94,27 @@ jobs:
7294
matrix:
7395
os: [ubuntu-latest, macos-latest, windows-latest]
7496
steps:
75-
- uses: actions/checkout@v6
76-
- uses: actions/setup-node@v6
97+
- name: Checkout
98+
uses: actions/checkout@v6
99+
100+
- name: Setup Node.js
101+
uses: actions/setup-node@v6
77102
with:
78103
node-version: "24"
79104
cache: "npm"
105+
106+
- name: Setup Bun
107+
uses: oven-sh/setup-bun@v2
108+
80109
- name: Install dependencies
81110
run: npm ci
111+
82112
- name: Generate types
83113
run: npm run generate-types
114+
84115
- name: Build
85116
run: npm run build
117+
86118
- name: Run E2E tests
87119
run: npm run test:e2e
88120

@@ -96,12 +128,18 @@ jobs:
96128
matrix:
97129
os: [ubuntu-latest, macos-latest, windows-latest]
98130
steps:
99-
- uses: actions/checkout@v6
100-
- uses: actions/setup-node@v6
131+
- name: Checkout
132+
uses: actions/checkout@v6
133+
134+
- name: Setup Node.js
135+
uses: actions/setup-node@v6
101136
with:
102137
node-version: "24"
103138
cache: "npm"
104139

140+
- name: Setup Bun
141+
uses: oven-sh/setup-bun@v2
142+
105143
- name: Install dependencies
106144
run: npm ci
107145

@@ -187,12 +225,18 @@ jobs:
187225
needs: unit
188226
runs-on: macos-latest
189227
steps:
190-
- uses: actions/checkout@v6
191-
- uses: actions/setup-node@v6
228+
- name: Checkout
229+
uses: actions/checkout@v6
230+
231+
- name: Setup Node.js
232+
uses: actions/setup-node@v6
192233
with:
193234
node-version: "24"
194235
cache: "npm"
195236

237+
- name: Setup Bun
238+
uses: oven-sh/setup-bun@v2
239+
196240
- name: Install dependencies
197241
run: npm ci
198242

@@ -236,12 +280,18 @@ jobs:
236280
needs: unit
237281
runs-on: ubuntu-latest
238282
steps:
239-
- uses: actions/checkout@v6
240-
- uses: actions/setup-node@v6
283+
- name: Checkout
284+
uses: actions/checkout@v6
285+
286+
- name: Setup Node.js
287+
uses: actions/setup-node@v6
241288
with:
242289
node-version: "24"
243290
cache: "npm"
244291

292+
- name: Setup Bun
293+
uses: oven-sh/setup-bun@v2
294+
245295
- name: Install dependencies
246296
run: npm ci
247297

@@ -293,12 +343,18 @@ jobs:
293343
needs: unit
294344
runs-on: windows-latest
295345
steps:
296-
- uses: actions/checkout@v6
297-
- uses: actions/setup-node@v6
346+
- name: Checkout
347+
uses: actions/checkout@v6
348+
349+
- name: Setup Node.js
350+
uses: actions/setup-node@v6
298351
with:
299352
node-version: "24"
300353
cache: "npm"
301354

355+
- name: Setup Bun
356+
uses: oven-sh/setup-bun@v2
357+
302358
- name: Install dependencies
303359
run: npm ci
304360

@@ -341,12 +397,18 @@ jobs:
341397
matrix:
342398
os: [ubuntu-latest, macos-latest, windows-latest]
343399
steps:
344-
- uses: actions/checkout@v6
345-
- uses: actions/setup-node@v6
400+
- name: Checkout
401+
uses: actions/checkout@v6
402+
403+
- name: Setup Node.js
404+
uses: actions/setup-node@v6
346405
with:
347406
node-version: "24"
348407
cache: "npm"
349408

409+
- name: Setup Bun
410+
uses: oven-sh/setup-bun@v2
411+
350412
- name: Install dependencies
351413
run: npm ci
352414

‎AGENTS.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,15 @@ Notes for LLM coding agents working on `hugo-extended`.
2626

2727
- **Binary installation**: `src/lib/install.ts`
2828
- Downloads Hugo release assets and verifies SHA-256 checksums.
29-
- **macOS**: uses `sudo installer -pkg ... -target /` (and then symlinks `bin/hugo` -> `/usr/local/bin/hugo`).
29+
- **macOS v0.153.0+**: uses `sudo installer -pkg ... -target /` (and then symlinks `bin/hugo` -> `/usr/local/bin/hugo`).
30+
- **macOS pre-v0.153.0**: extracts `.tar.gz` archive into `bin/` (no sudo required).
3031
- **non-macOS**: extracts archive into `bin/` and `chmod +x`.
3132

33+
- **Environment variables**: `src/lib/env.ts`
34+
- Centralized handling of all `HUGO_*` environment variables.
35+
- Exports `getEnvConfig()` for reading parsed config, `logger` for quiet-aware logging.
36+
- Exports `ENV_VAR_DOCS` for programmatic access to variable metadata.
37+
3238
- **Postinstall**: `postinstall.js`
3339
- For published packages (where `dist/` exists), runs the compiled installer.
3440
- For repo/dev/CI (where `dist/` may not exist), exits successfully and skips installation.
@@ -110,3 +116,29 @@ npm run test:coverage # coverage via v8
110116

111117
- If you touch exports in `src/hugo.ts`:
112118
- Remember: consumers rely on the **default export being callable** (binary path) and having builder methods attached.
119+
120+
- If you touch environment variables (`src/lib/env.ts`):
121+
- All env vars are defined in `ENV_VARS` with name, aliases, parse function, and description.
122+
- Boolean env vars accept: `1`, `true`, `yes`, `on` (case-insensitive).
123+
- Use `getEnvConfig()` to read config; use `logger.info/warn/error` for quiet-aware output.
124+
- `postinstall.js` has its own minimal env parsing (can't import TypeScript modules).
125+
126+
## Environment variables reference
127+
128+
| Variable | Type | Description |
129+
|----------|------|-------------|
130+
| `HUGO_OVERRIDE_VERSION` | string | Install a different Hugo version (ignores package.json) |
131+
| `HUGO_NO_EXTENDED` | boolean | Force vanilla Hugo instead of Extended |
132+
| `HUGO_SKIP_DOWNLOAD` | boolean | Skip postinstall binary download |
133+
| `HUGO_BIN_PATH` | string | Use a pre-existing Hugo binary |
134+
| `HUGO_MIRROR_BASE_URL` | string | Custom download mirror URL |
135+
| `HUGO_SKIP_CHECKSUM` | boolean | Skip SHA-256 verification |
136+
| `HUGO_QUIET` | boolean | Suppress installation output |
137+
138+
Some variables have aliases (e.g., `HUGO_FORCE_STANDARD` → `HUGO_NO_EXTENDED`, `HUGO_SILENT` → `HUGO_QUIET`). Check `ENV_VARS` in `src/lib/env.ts` for the full list.
139+
140+
### Version-dependent behavior
141+
142+
- **macOS v0.153.0+**: Hugo ships as `.pkg` installer, requires `sudo`.
143+
- **macOS pre-v0.153.0**: Hugo ships as `.tar.gz`, extracted to `bin/` directly.
144+
- The `usesMacOSPkg(version)` and `compareVersions(a, b)` utilities in `src/lib/utils.ts` handle this.

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,36 @@ Hugo Extended is automatically used on supported platforms:
212212
| Windows | ARM64 | ❌ (vanilla Hugo) |
213213
| FreeBSD | x64 | ❌ (vanilla Hugo) |
214214

215+
## Environment Variables
216+
217+
Customize installation and runtime behavior with these environment variables:
218+
219+
| Variable | Description |
220+
|----------|-------------|
221+
| `HUGO_OVERRIDE_VERSION` | Install a specific Hugo version instead of the package version. Example: `HUGO_OVERRIDE_VERSION=0.139.0 npm install` |
222+
| `HUGO_NO_EXTENDED` | Force vanilla Hugo instead of Extended edition. Example: `HUGO_NO_EXTENDED=1 npm install` |
223+
| `HUGO_SKIP_DOWNLOAD` | Skip the postinstall binary download entirely. Useful for CI caching or Docker layer optimization. |
224+
| `HUGO_BIN_PATH` | Use a pre-existing Hugo binary instead of the bundled one. Example: `HUGO_BIN_PATH=/usr/local/bin/hugo` |
225+
| `HUGO_MIRROR_BASE_URL` | Download from a custom mirror instead of GitHub releases. Example: `HUGO_MIRROR_BASE_URL=https://mirror.example.com/hugo` |
226+
| `HUGO_SKIP_CHECKSUM` | Skip SHA-256 checksum verification. **Use with caution.** |
227+
| `HUGO_QUIET` | Suppress installation progress output. |
228+
229+
### Examples
230+
231+
```sh
232+
# Install a specific older version
233+
HUGO_OVERRIDE_VERSION=0.139.0 npm install hugo-extended
234+
235+
# Skip download for CI caching (when binary is already cached)
236+
HUGO_SKIP_DOWNLOAD=1 npm ci
237+
238+
# Use smaller vanilla Hugo (no SCSS support)
239+
HUGO_NO_EXTENDED=1 npm install hugo-extended
240+
241+
# Use a corporate mirror
242+
HUGO_MIRROR_BASE_URL=https://internal.example.com/hugo npm install hugo-extended
243+
```
244+
215245
## Troubleshooting
216246

217247
### Hugo binary not found

0 commit comments

Comments
 (0)