@link-foundation/universal-translator 0.0.0-stage → 0.11.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +530 -0
- package/LICENSE +24 -0
- package/README.md +410 -2
- package/bin/universal-translator.js +95 -0
- package/package.json +89 -4
- package/src/index.d.ts +27 -0
- package/src/index.js +28 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.11.31
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Fix every open CI correctness and resilience issue in the pipeline: scope the
|
|
8
|
+
Docker buildx cache, retry transient fetch and download failures, make the
|
|
9
|
+
budget wrapper escalate to SIGKILL, add a terminal status gate to every
|
|
10
|
+
workflow with supersede detection, verify the husky install, make the jscpd
|
|
11
|
+
gate analyse real files, guard the package manager declaration, turn on
|
|
12
|
+
command-stream errexit, gate staged formatting before release commits, add
|
|
13
|
+
release-preflight credential checks, and sweep zizmor/actionlint/persisted
|
|
14
|
+
credentials/link-recheck fixes across the workflows.
|
|
15
|
+
|
|
16
|
+
Allow protected releases to use the built-in GitHub Actions token after
|
|
17
|
+
metadata-only attestation, wait through npm registry propagation without
|
|
18
|
+
republishing, and skip deleted changesets during staged formatting checks.
|
|
19
|
+
|
|
20
|
+
Make protected-branch release fallbacks wait for real pull-request checks with
|
|
21
|
+
a dedicated automation token, and pin every Linux CI job to Ubuntu 24.04.
|
|
22
|
+
|
|
23
|
+
Harden CI verdicts, Docker manifest publication, timeout cleanup, broken-link
|
|
24
|
+
rechecks, and contributor-authored workflow logs, and refresh vulnerable
|
|
25
|
+
transitive development dependencies.
|
|
26
|
+
|
|
27
|
+
## 0.11.30
|
|
28
|
+
|
|
29
|
+
### Patch Changes
|
|
30
|
+
|
|
31
|
+
- 8b129f9: Recognise npm's E409 "Cannot publish over previously staged version" wording as an already-published conflict in `publish-retry`, so a release that reached the registry verifies instead of failing the job.
|
|
32
|
+
|
|
33
|
+
## 0.11.29
|
|
34
|
+
|
|
35
|
+
### Patch Changes
|
|
36
|
+
|
|
37
|
+
- 0cd60b8: Bound the use-m CDN fetch with a per-attempt deadline and a retry, and report a load failure from the script that needs it.
|
|
38
|
+
|
|
39
|
+
`loadUse()` fetched `https://unpkg.com/use-m/use.js` with a bare `fetch()`, so a CDN blip surfaced as `TypeError: fetch failed` — a message naming neither the CDN nor the URL — and a connection that was accepted but never answered was bounded only by undici's 300 s `headersTimeout`. Each attempt now carries a 15 s deadline enforced by an `AbortController`, a failed attempt is retried up to three times with exponential backoff (51 s worst case), and the final error names the URL, the attempt count and the underlying reason, keeping the original failure as its `cause`.
|
|
40
|
+
|
|
41
|
+
The seven release scripts that loaded these modules at module scope now go through `scripts/bootstrap-dependencies.mjs`, which prints a GitHub `::error::` annotation and writes the fallback outputs the workflow reads — `published=false` for `publish-to-npm.mjs`, `version_committed=false` for `version-and-commit.mjs` — so a CDN outage no longer leaves a job with an empty `GITHUB_OUTPUT` and a loader stack.
|
|
42
|
+
|
|
43
|
+
## 0.11.28
|
|
44
|
+
|
|
45
|
+
### Patch Changes
|
|
46
|
+
|
|
47
|
+
- Configure the release and merge-simulation commit author as `41898282+github-actions[bot]@users.noreply.github.com` in `scripts/version-and-commit.mjs` and `scripts/simulate-fresh-merge.sh`, so those commits are attributed to the `github-actions[bot]` account and no longer require an extra approval under rulesets with `require_extra_approval_for_unattributed_changes`.
|
|
48
|
+
|
|
49
|
+
Add a scheduled fail-closed high-severity audit for every committed npm lock.
|
|
50
|
+
|
|
51
|
+
Ignore successful redirects when checking Lychee reports for broken links.
|
|
52
|
+
|
|
53
|
+
Lint the workflows themselves: a new `workflows` check runs `actionlint` (from the Docker image that bundles shellcheck) and `zizmor`, and the findings they reported are fixed — the manifest digest list is built as an array, the packaging retry logs its attempt number, the npm wait passes the release version through the environment, and third-party actions are pinned to commit hashes.
|
|
54
|
+
|
|
55
|
+
Fail the web archive check on lychee errors that have no http(s) URL
|
|
56
|
+
|
|
57
|
+
`scripts/check-web-archive.mjs` only extracted `http(s)` links from the lychee
|
|
58
|
+
report, so errors such as a missing local file or an unresolvable root-relative
|
|
59
|
+
link were silently dropped. When those were the only errors the script printed
|
|
60
|
+
"No broken URLs found" and set `all_archived=true`, masking a failing lychee
|
|
61
|
+
run. The parser now matches the status marker instead of the URL and splits the
|
|
62
|
+
results into archivable URLs and links the Wayback Machine cannot answer; the
|
|
63
|
+
latter are annotated as errors and force `all_archived=false` with exit code 1.
|
|
64
|
+
Adds regression tests over a captured lychee report fixture.
|
|
65
|
+
|
|
66
|
+
Compare change detection paths package-relative so the ignore list (`examples/`, `.changeset/`, `experiments/`, `dev/log/`, `docs/case-studies/`) also matches in the multi-language layout, and stop reporting other languages' files as JavaScript code changes.
|
|
67
|
+
|
|
68
|
+
Publish Docker images for both amd64 and arm64 using native runners and a multi-architecture manifest.
|
|
69
|
+
|
|
70
|
+
Suppress the reviewed DEP0005 warning from the Docker manifest artifact download step.
|
|
71
|
+
|
|
72
|
+
Land the release version bump through a pull request when a repository ruleset declines the direct push to `main`, and stop reporting a GH013 rule violation as a lost push race.
|
|
73
|
+
|
|
74
|
+
Give long CI steps their own execution budget so an overrun reports `failure` instead of `cancelled`.
|
|
75
|
+
|
|
76
|
+
Fail broken-link checks until archived replacements are applied to dead links.
|
|
77
|
+
|
|
78
|
+
Load `command-stream` and `lino-arguments` through a shared use-m interop shim so the release scripts work on Node 24.
|
|
79
|
+
|
|
80
|
+
Node 22.12+ adds a synthetic `module.exports` named export to CommonJS namespaces whose names cannot be inferred, which stops use-m from unwrapping the callable default. Destructuring `$` off the result therefore yields `undefined` and every release script fails with `TypeError: $ is not a function` on the Node 24 runners the workflows request. `scripts/use-module.mjs` normalises the namespace, reports the HTTP status when `use.js` cannot be fetched, names the observed keys when no callable export is found, and traces the resolved shape under `CI_SCRIPTS_DEBUG=1`.
|
|
81
|
+
|
|
82
|
+
Report why `scripts/wait-for-npm.mjs` could not confirm a release. The check
|
|
83
|
+
queries the npm registry over HTTP and returns `{ available, status, httpStatus,
|
|
84
|
+
url, error }`, so an HTTP 404 ("not published") is distinguished from an
|
|
85
|
+
unanswered probe (5xx, rate limit, proxy, DNS). Every attempt logs its outcome,
|
|
86
|
+
and an unanswered probe no longer claims the version "did not become available
|
|
87
|
+
on npm" — it says the publish status is unknown and points at the registry URL
|
|
88
|
+
to check. The step also exposes an `npm_check_status` output.
|
|
89
|
+
|
|
90
|
+
## 0.11.27
|
|
91
|
+
|
|
92
|
+
### Patch Changes
|
|
93
|
+
|
|
94
|
+
- 53519f1: Report release pipeline timeout cancellations as visible failures on the default branch.
|
|
95
|
+
|
|
96
|
+
## 0.11.26
|
|
97
|
+
|
|
98
|
+
### Patch Changes
|
|
99
|
+
|
|
100
|
+
- 328d858: Add CodeQL analysis for JavaScript and GitHub Actions plus high-severity dependency review for pull requests.
|
|
101
|
+
|
|
102
|
+
## 0.11.25
|
|
103
|
+
|
|
104
|
+
### Patch Changes
|
|
105
|
+
|
|
106
|
+
- 8af8547: Require successful lint and test quality gates before manual releases can publish.
|
|
107
|
+
|
|
108
|
+
## 0.11.24
|
|
109
|
+
|
|
110
|
+
### Patch Changes
|
|
111
|
+
|
|
112
|
+
- dd8a969: Reject unsupported keys in generated workflow concurrency blocks.
|
|
113
|
+
|
|
114
|
+
## 0.11.23
|
|
115
|
+
|
|
116
|
+
### Patch Changes
|
|
117
|
+
|
|
118
|
+
- e73716a: Harden workflow inputs, checkout configuration, and deployment concurrency.
|
|
119
|
+
|
|
120
|
+
## 0.11.22
|
|
121
|
+
|
|
122
|
+
### Patch Changes
|
|
123
|
+
|
|
124
|
+
- d0b42fa: Keep excluded-directory changes from activating change-gated CI jobs on pull
|
|
125
|
+
requests and direct pushes.
|
|
126
|
+
|
|
127
|
+
## 0.11.21
|
|
128
|
+
|
|
129
|
+
### Patch Changes
|
|
130
|
+
|
|
131
|
+
- 5bf9619: Quote the fresh merge base ref to prevent shell word splitting.
|
|
132
|
+
|
|
133
|
+
## 0.11.20
|
|
134
|
+
|
|
135
|
+
### Patch Changes
|
|
136
|
+
|
|
137
|
+
- dfd681f: Report ESLint warnings only on lines changed relative to the base branch, so unchanged findings such as `local/no-changelog-comments` stop repeating on every run. Errors are still reported for all files.
|
|
138
|
+
|
|
139
|
+
## 0.11.19
|
|
140
|
+
|
|
141
|
+
### Patch Changes
|
|
142
|
+
|
|
143
|
+
- 8608672: Split publish and verification failure domains in `publish-to-npm.mjs`: verification now polls the npm registry with exponential backoff, and a verification miss no longer re-runs `changeset publish`.
|
|
144
|
+
|
|
145
|
+
## 0.11.18
|
|
146
|
+
|
|
147
|
+
### Patch Changes
|
|
148
|
+
|
|
149
|
+
- 6b3289a: Build the Dockerfile on pull requests via a new `docker-build` job, so a broken image fails the pull request instead of only surfacing after the package is published. The build uses `push: false` with `load: true` (works for fork pull requests, which have no registry credentials) and the GHA layer cache. Repositories without a Dockerfile skip the job automatically.
|
|
150
|
+
|
|
151
|
+
## 0.11.17
|
|
152
|
+
|
|
153
|
+
### Patch Changes
|
|
154
|
+
|
|
155
|
+
- ebaa52a: Add a least-privilege top-level `permissions: contents: read` block to `release.yml` and `links.yml` so jobs no longer inherit the repository default `GITHUB_TOKEN` scope, with write access escalated only on the publishing jobs.
|
|
156
|
+
|
|
157
|
+
## 0.11.16
|
|
158
|
+
|
|
159
|
+
### Patch Changes
|
|
160
|
+
|
|
161
|
+
- 1349837: Suppress the Git default-branch hint during release workflow checkout.
|
|
162
|
+
|
|
163
|
+
## 0.11.15
|
|
164
|
+
|
|
165
|
+
### Patch Changes
|
|
166
|
+
|
|
167
|
+
- f04c820: Quiet release logs by checking npm package versions through the registry HTTP API and removing deprecated setup-node `always-auth` config before publish-job npm commands run.
|
|
168
|
+
|
|
169
|
+
## 0.11.14
|
|
170
|
+
|
|
171
|
+
### Patch Changes
|
|
172
|
+
|
|
173
|
+
- 63b31c3: Harden generated preview-image pushes against main branch non-fast-forward races.
|
|
174
|
+
|
|
175
|
+
## 0.11.13
|
|
176
|
+
|
|
177
|
+
### Patch Changes
|
|
178
|
+
|
|
179
|
+
- Add a warning-level ESLint rule for changelog-style comments and strings.
|
|
180
|
+
|
|
181
|
+
Detect code changes from real merge commits pushed to main with the first-parent
|
|
182
|
+
merge diff while preserving pull request synthetic merge behavior.
|
|
183
|
+
|
|
184
|
+
## 0.11.12
|
|
185
|
+
|
|
186
|
+
### Patch Changes
|
|
187
|
+
|
|
188
|
+
- 89fb151: Ignore stray Markdown files when checking for pending changesets.
|
|
189
|
+
|
|
190
|
+
## 0.11.11
|
|
191
|
+
|
|
192
|
+
### Patch Changes
|
|
193
|
+
|
|
194
|
+
- d2e3932: Require exact changelog version headers when extracting GitHub release notes.
|
|
195
|
+
- e7356e9: Fail release-time changeset merging when any pending changeset is malformed.
|
|
196
|
+
|
|
197
|
+
## 0.11.10
|
|
198
|
+
|
|
199
|
+
### Patch Changes
|
|
200
|
+
|
|
201
|
+
- 9915756: Auto-detect single-language versus `js/` monorepo layouts when naming GitHub
|
|
202
|
+
releases, namespace multi-language JavaScript tags as `js_v<version>`, and
|
|
203
|
+
normalize prefixed tags before linking npm version badges.
|
|
204
|
+
|
|
205
|
+
## 0.11.9
|
|
206
|
+
|
|
207
|
+
### Patch Changes
|
|
208
|
+
|
|
209
|
+
- 49a8205: Add a post-publish smoke test that installs the just-published npm package in a clean project and verifies its entry points.
|
|
210
|
+
|
|
211
|
+
## 0.11.8
|
|
212
|
+
|
|
213
|
+
### Patch Changes
|
|
214
|
+
|
|
215
|
+
- 391530e: Skip the slow CI test matrix for pull requests that only touch non-code files.
|
|
216
|
+
|
|
217
|
+
## 0.11.7
|
|
218
|
+
|
|
219
|
+
### Patch Changes
|
|
220
|
+
|
|
221
|
+
- 674f9ce: Fix npm release path for brand-new packages (issue #77):
|
|
222
|
+
- `publish-to-npm.mjs` now classifies authentication / registry-configuration
|
|
223
|
+
failures (404/401/403, `access token expired`, `ENEEDAUTH`, etc.) as
|
|
224
|
+
non-retryable and fails fast with actionable guidance instead of retrying
|
|
225
|
+
`MAX_RETRIES` times and hiding the real cause behind a generic error.
|
|
226
|
+
- The `release` and `instant-release` publish steps now pass an optional
|
|
227
|
+
`NODE_AUTH_TOKEN` sourced from `secrets.NPM_TOKEN`, providing a first-publish
|
|
228
|
+
bootstrap path. OIDC trusted publishing remains the steady-state mechanism;
|
|
229
|
+
the token is only needed for the very first release of a new package.
|
|
230
|
+
|
|
231
|
+
## 0.11.6
|
|
232
|
+
|
|
233
|
+
### Patch Changes
|
|
234
|
+
|
|
235
|
+
- 8ca3e32: Harden the `publish-dockerhub` buildx boot against transient Docker Hub registry outages. A new reusable `setup-buildx-resilient` composite action pre-pulls the pinned `moby/buildkit` image with retries and a `mirror.gcr.io` pull-through fallback, then boots buildx with the driver image pinned to the locally cached copy so a `registry-1.docker.io` blip no longer fails the publish job (issue #75).
|
|
236
|
+
|
|
237
|
+
## 0.11.5
|
|
238
|
+
|
|
239
|
+
### Patch Changes
|
|
240
|
+
|
|
241
|
+
- 312a2fe: Add a `concurrency` block to the Broken Link Checker workflow (`links.yml`) so redundant runs are cancelled on new commits, consistent with the other workflows in the template.
|
|
242
|
+
|
|
243
|
+
## 0.11.4
|
|
244
|
+
|
|
245
|
+
### Patch Changes
|
|
246
|
+
|
|
247
|
+
- 35696cc: Cap generated GitHub release notes before creating releases so oversized changelog
|
|
248
|
+
entries link to the full tagged changelog instead of failing GitHub API
|
|
249
|
+
validation.
|
|
250
|
+
|
|
251
|
+
## 0.11.3
|
|
252
|
+
|
|
253
|
+
### Patch Changes
|
|
254
|
+
|
|
255
|
+
- a8e4030: Run the preview screenshot regeneration workflow inside the official Playwright container to avoid stalled Chromium downloads in CI, and keep the desktop packaging job on Node 20 while verifying package output before artifact upload.
|
|
256
|
+
|
|
257
|
+
## 0.11.2
|
|
258
|
+
|
|
259
|
+
### Patch Changes
|
|
260
|
+
|
|
261
|
+
- aeec4cb: Enforce the 1500-line architecture limit across all JavaScript (`.js`, `.mjs`, `.cjs`) and Markdown (`.md`) files in the `check-file-line-limits` CI gate, lower the documentation limit from 2500 to 1500, and exempt case-study generated-data files explicitly.
|
|
262
|
+
|
|
263
|
+
## 0.11.1
|
|
264
|
+
|
|
265
|
+
### Patch Changes
|
|
266
|
+
|
|
267
|
+
- 8cd0d70: Correct CI workflow concurrency and preview failure artifact handling in the template.
|
|
268
|
+
|
|
269
|
+
## 0.11.0
|
|
270
|
+
|
|
271
|
+
### Minor Changes
|
|
272
|
+
|
|
273
|
+
- e7025ed: Add a release-time `preview-regen` job to `example-app.yml` and a
|
|
274
|
+
`scripts/update-preview-images.mjs` driver that boot the universal example app
|
|
275
|
+
in a headless Chromium via `browser-commander` + Playwright, capture a
|
|
276
|
+
locale × theme matrix of screenshots into `docs/screenshots/example-app/`, and
|
|
277
|
+
commit any drift back to `main` with `[skip ci]`. Adds the matching
|
|
278
|
+
`npm run example:web:preview-images` script.
|
|
279
|
+
|
|
280
|
+
## 0.10.2
|
|
281
|
+
|
|
282
|
+
### Patch Changes
|
|
283
|
+
|
|
284
|
+
- f044604: Document the one-time **Settings → Pages → Source = GitHub Actions** prerequisite for the example app deployment, and note it in a comment above the `pages-deploy` job.
|
|
285
|
+
|
|
286
|
+
## 0.10.1
|
|
287
|
+
|
|
288
|
+
### Patch Changes
|
|
289
|
+
|
|
290
|
+
- ede9f84: Publish the template as the real link-foundation example package and add the globally installable CLI entry point.
|
|
291
|
+
|
|
292
|
+
## 0.10.0
|
|
293
|
+
|
|
294
|
+
### Minor Changes
|
|
295
|
+
|
|
296
|
+
- 5a81a7f: Add a universal React example app with GitHub Pages, Electron desktop, and Capacitor mobile build paths.
|
|
297
|
+
|
|
298
|
+
## 0.9.0
|
|
299
|
+
|
|
300
|
+
### Minor Changes
|
|
301
|
+
|
|
302
|
+
- f23283c: Add an optional Docker Hub publishing path that waits for the exact npm
|
|
303
|
+
package version before tagging Docker images.
|
|
304
|
+
|
|
305
|
+
## 0.8.6
|
|
306
|
+
|
|
307
|
+
### Patch Changes
|
|
308
|
+
|
|
309
|
+
- acccf75: Format GitHub release names as human-readable `[Language] x.y.z` titles while keeping prefixed tag names unchanged.
|
|
310
|
+
|
|
311
|
+
## 0.8.5
|
|
312
|
+
|
|
313
|
+
### Patch Changes
|
|
314
|
+
|
|
315
|
+
- Fail GitHub release creation on unexpected gh api errors and clearly skip releases that already exist.
|
|
316
|
+
|
|
317
|
+
Enforce npm and Node.js minimum versions for trusted publishing setup and resolve a supported npm 11 tarball for fallback installs.
|
|
318
|
+
|
|
319
|
+
## 0.8.4
|
|
320
|
+
|
|
321
|
+
### Patch Changes
|
|
322
|
+
|
|
323
|
+
- 031f7cd: Add explicit CI job timeouts and per-test runner timeout limits.
|
|
324
|
+
|
|
325
|
+
## 0.8.3
|
|
326
|
+
|
|
327
|
+
### Patch Changes
|
|
328
|
+
|
|
329
|
+
- bdaa4b7: Derive release script package names from package.json instead of template placeholders.
|
|
330
|
+
|
|
331
|
+
## 0.8.2
|
|
332
|
+
|
|
333
|
+
### Patch Changes
|
|
334
|
+
|
|
335
|
+
- d179bb7: Add warning annotations for files approaching the CI file line limit.
|
|
336
|
+
|
|
337
|
+
## 0.8.1
|
|
338
|
+
|
|
339
|
+
### Patch Changes
|
|
340
|
+
|
|
341
|
+
- f0c69af: Normalize language-prefixed release tags before building npm shields.io badge URLs.
|
|
342
|
+
|
|
343
|
+
## 0.8.0
|
|
344
|
+
|
|
345
|
+
### Minor Changes
|
|
346
|
+
|
|
347
|
+
- 3e45a9c: Add `--tag-prefix` option to release scripts for multi-language repos
|
|
348
|
+
|
|
349
|
+
The `create-github-release.mjs` and `format-github-release.mjs` scripts now accept a `--tag-prefix` CLI parameter (defaulting to `v`) that allows users to customize the git tag prefix. This enables use in multi-language repositories where different language packages need distinct tag prefixes (e.g., `js-v1.0.0` vs `rust-v1.0.0`).
|
|
350
|
+
|
|
351
|
+
## 0.7.3
|
|
352
|
+
|
|
353
|
+
### Patch Changes
|
|
354
|
+
|
|
355
|
+
- ae2cc9a: Add self-healing release mechanism that checks npm registry for unpublished versions
|
|
356
|
+
|
|
357
|
+
## 0.7.2
|
|
358
|
+
|
|
359
|
+
### Patch Changes
|
|
360
|
+
|
|
361
|
+
- 9126e16: fix: npm upgrade fallbacks and Node.js 24.x upgrade for CI/CD
|
|
362
|
+
- Upgrade Node.js from 20.x to 24.x in all workflow files (avoids broken npm in Node.js 22.22.2)
|
|
363
|
+
- Add 4-strategy fallback chain to setup-npm.mjs (standard, curl tarball, npx, corepack)
|
|
364
|
+
- Update GitHub Actions to latest versions (checkout v6, setup-node v6, create-pull-request v8)
|
|
365
|
+
- Add case study documentation for issue #33
|
|
366
|
+
|
|
367
|
+
## 0.7.1
|
|
368
|
+
|
|
369
|
+
### Patch Changes
|
|
370
|
+
|
|
371
|
+
- 6916409: Use per-commit diff instead of full-PR diff for CI change detection
|
|
372
|
+
|
|
373
|
+
## 0.7.0
|
|
374
|
+
|
|
375
|
+
### Minor Changes
|
|
376
|
+
|
|
377
|
+
- 983789a: Add CI/CD best practices from hive-mind: fast-fail job ordering, test compilation, file line limits check, secrets detection, documentation validation, extracted fresh merge simulation script, and proper cancellation propagation
|
|
378
|
+
|
|
379
|
+
## 0.6.0
|
|
380
|
+
|
|
381
|
+
### Minor Changes
|
|
382
|
+
|
|
383
|
+
- 8961862: Add automated broken link checker with Web Archive fallback suggestions
|
|
384
|
+
- Add `.github/workflows/links.yml` with lychee-action for link checking in Markdown and HTML files
|
|
385
|
+
- Add `scripts/check-web-archive.mjs` to check broken links against the Wayback Machine API
|
|
386
|
+
- Add `.lycheeignore` for excluding known false-positive URLs (localhost, example.com, etc.)
|
|
387
|
+
- Update `README.md` to document the broken link checker feature
|
|
388
|
+
- Scheduled weekly check (Mondays at 09:00 UTC) to catch links that break over time
|
|
389
|
+
- On PRs, broken links with no Web Archive fallback will fail the check
|
|
390
|
+
- For broken links that have archived versions, provides actionable replacement suggestions
|
|
391
|
+
- On scheduled runs, automatically creates a GitHub Issue with the full broken links report
|
|
392
|
+
|
|
393
|
+
Fixes #27
|
|
394
|
+
|
|
395
|
+
## 0.5.1
|
|
396
|
+
|
|
397
|
+
### Patch Changes
|
|
398
|
+
|
|
399
|
+
- e398190: Add comprehensive best practices comparison and improve CI concurrency
|
|
400
|
+
- Add DETAILED-COMPARISON.md with side-by-side analysis of ALL scripts, workflows, and configurations
|
|
401
|
+
- Implement cancel-in-progress for main branch concurrency (hive-mind Issue #1274 fix)
|
|
402
|
+
- Fix max-lines documentation (1500, not 1000)
|
|
403
|
+
- Reference detailed comparison from BEST-PRACTICES.md
|
|
404
|
+
|
|
405
|
+
## 0.5.0
|
|
406
|
+
|
|
407
|
+
### Minor Changes
|
|
408
|
+
|
|
409
|
+
- 66211b5: Add fresh merge simulation to CI/CD to prevent stale merge preview issues
|
|
410
|
+
- Add "Simulate fresh merge with base branch" step to lint and test jobs
|
|
411
|
+
- This ensures PR CI validates the actual merge result, not a stale snapshot
|
|
412
|
+
- Prevents CI failures on main branch after merging PRs that sat open for days
|
|
413
|
+
- Add case study documentation for issue #23 with root cause analysis
|
|
414
|
+
- Add ignore patterns for case study data files in ESLint and Prettier
|
|
415
|
+
|
|
416
|
+
See docs/case-studies/issue-23 for detailed analysis of the stale merge preview problem.
|
|
417
|
+
|
|
418
|
+
Fixes #23
|
|
419
|
+
|
|
420
|
+
## 0.4.0
|
|
421
|
+
|
|
422
|
+
### Minor Changes
|
|
423
|
+
|
|
424
|
+
- e6c2691: Add multi-language repository support for CI/CD scripts
|
|
425
|
+
- Add `scripts/js-paths.mjs` utility for automatic JavaScript package root detection
|
|
426
|
+
- Support both `./package.json` (single-language) and `./js/package.json` (multi-language repos)
|
|
427
|
+
- Add `--legacy-peer-deps` flag to npm install commands in release scripts to fix ERESOLVE errors
|
|
428
|
+
- Save and restore working directory after `cd` commands to fix `command-stream` library's `process.chdir()` behavior
|
|
429
|
+
- Add case study documentation with root cause analysis in `docs/case-studies/issue-21/`
|
|
430
|
+
|
|
431
|
+
## 0.3.0
|
|
432
|
+
|
|
433
|
+
### Minor Changes
|
|
434
|
+
|
|
435
|
+
- 80d9c84: Add CI check to prevent manual version modification in package.json
|
|
436
|
+
- Added `check-version.mjs` script that detects manual version changes in PRs
|
|
437
|
+
- Added `check-changesets.mjs` script to check for pending changesets (converted from inline shell)
|
|
438
|
+
- Added `version-check` job to release.yml workflow
|
|
439
|
+
- Automated release PRs (changeset-release/_ and changeset-manual-release-_) are automatically skipped
|
|
440
|
+
|
|
441
|
+
## 0.2.2
|
|
442
|
+
|
|
443
|
+
### Patch Changes
|
|
444
|
+
|
|
445
|
+
- 9a12139: Fix CI/CD check differences between pull request and push events
|
|
446
|
+
|
|
447
|
+
Changes:
|
|
448
|
+
- Add `detect-changes` job with cross-platform `detect-code-changes.mjs` script
|
|
449
|
+
- Make lint job independent of changeset-check (runs based on file changes only)
|
|
450
|
+
- Allow docs-only PRs without changeset requirement
|
|
451
|
+
- Handle changeset-check 'skipped' state in dependent jobs
|
|
452
|
+
- Exclude `.changeset/`, `docs/`, `experiments/`, `examples/` folders and markdown files from code changes detection
|
|
453
|
+
|
|
454
|
+
## 0.2.1
|
|
455
|
+
|
|
456
|
+
### Patch Changes
|
|
457
|
+
|
|
458
|
+
- 55aef41: Make Bun the primary runtime choice throughout the template
|
|
459
|
+
- Update all shebangs from `#!/usr/bin/env node` to `#!/usr/bin/env bun` in scripts, experiments, and case studies
|
|
460
|
+
- Update README.md to prioritize Bun in all sections (features, development, runtime support, package managers, scripts reference)
|
|
461
|
+
- Update examples to list Bun first
|
|
462
|
+
- Bun now described as "Primary runtime with highest performance" and "Primary choice" for package management
|
|
463
|
+
- Maintains full compatibility with Node.js and Deno
|
|
464
|
+
|
|
465
|
+
## 0.2.0
|
|
466
|
+
|
|
467
|
+
### Minor Changes
|
|
468
|
+
|
|
469
|
+
- d3f7fcd: Improve changeset CI/CD robustness for concurrent PRs
|
|
470
|
+
- Update validate-changeset.mjs to only check changesets ADDED by the current PR (not pre-existing ones)
|
|
471
|
+
- Add merge-changesets.mjs script to combine multiple pending changesets during release
|
|
472
|
+
- Merged changesets use highest version bump type (major > minor > patch) and combine descriptions chronologically
|
|
473
|
+
- Update release workflow to pass SHA environment variables and add merge step
|
|
474
|
+
- Add comprehensive case study documentation for the CI/CD improvement
|
|
475
|
+
- This prevents PR failures when multiple PRs merge before a release cycle completes
|
|
476
|
+
|
|
477
|
+
## 0.1.4
|
|
478
|
+
|
|
479
|
+
### Patch Changes
|
|
480
|
+
|
|
481
|
+
- e9703b9: Add ESLint complexity rules with reasonable thresholds
|
|
482
|
+
|
|
483
|
+
## 0.1.3
|
|
484
|
+
|
|
485
|
+
### Patch Changes
|
|
486
|
+
|
|
487
|
+
- 0198aaa: Add case study documentation comparing best practices from effect-template
|
|
488
|
+
|
|
489
|
+
This changeset adds comprehensive documentation analyzing best practices from
|
|
490
|
+
ProverCoderAI/effect-template repository, identifying gaps in our current setup,
|
|
491
|
+
and providing prioritized recommendations for improvements.
|
|
492
|
+
|
|
493
|
+
Key findings include missing best practices like code duplication detection (jscpd),
|
|
494
|
+
ESLint complexity rules, VS Code settings, and test coverage thresholds.
|
|
495
|
+
|
|
496
|
+
## 0.1.2
|
|
497
|
+
|
|
498
|
+
### Patch Changes
|
|
499
|
+
|
|
500
|
+
- 2ea9b78: Enforce strict no-unused-vars ESLint rule without exceptions. All unused variables, arguments, and caught errors must now be removed or used. The `_` prefix no longer suppresses unused variable warnings.
|
|
501
|
+
|
|
502
|
+
## 0.1.1
|
|
503
|
+
|
|
504
|
+
### Patch Changes
|
|
505
|
+
|
|
506
|
+
- 042e877: Fix GitHub release formatting to support Major/Minor/Patch changes
|
|
507
|
+
|
|
508
|
+
The release formatting script now correctly handles all changeset types (Major, Minor, Patch) instead of only Patch changes. This ensures that:
|
|
509
|
+
- Section headers are removed from release notes
|
|
510
|
+
- PR detection works for all release types
|
|
511
|
+
- NPM badges are added correctly
|
|
512
|
+
|
|
513
|
+
## 0.1.0
|
|
514
|
+
|
|
515
|
+
### Minor Changes
|
|
516
|
+
|
|
517
|
+
- 65d76dc: Initial template setup with complete AI-driven development pipeline
|
|
518
|
+
|
|
519
|
+
Features:
|
|
520
|
+
- Multi-runtime support for Node.js, Bun, and Deno
|
|
521
|
+
- Universal testing with test-anywhere framework
|
|
522
|
+
- Automated release workflow with changesets
|
|
523
|
+
- GitHub Actions CI/CD pipeline with 9 test combinations
|
|
524
|
+
- Code quality tools: ESLint + Prettier with Husky pre-commit hooks
|
|
525
|
+
- Package manager agnostic design
|
|
526
|
+
|
|
527
|
+
All notable changes to this project will be documented in this file.
|
|
528
|
+
|
|
529
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
530
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
package/LICENSE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
This is free and unencumbered software released into the public domain.
|
|
2
|
+
|
|
3
|
+
Anyone is free to copy, modify, publish, use, compile, sell, or
|
|
4
|
+
distribute this software, either in source code form or as a compiled
|
|
5
|
+
binary, for any purpose, commercial or non-commercial, and by any
|
|
6
|
+
means.
|
|
7
|
+
|
|
8
|
+
In jurisdictions that recognize copyright laws, the author or authors
|
|
9
|
+
of this software dedicate any and all copyright interest in the
|
|
10
|
+
software to the public domain. We make this dedication for the benefit
|
|
11
|
+
of the public at large and to the detriment of our heirs and
|
|
12
|
+
successors. We intend this dedication to be an overt act of
|
|
13
|
+
relinquishment in perpetuity of all present and future rights to this
|
|
14
|
+
software under copyright law.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
19
|
+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
20
|
+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
21
|
+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
|
23
|
+
|
|
24
|
+
For more information, please refer to <https://unlicense.org>
|
package/README.md
CHANGED
|
@@ -1,3 +1,411 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @link-foundation/universal-translator
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
JavaScript/TypeScript package with a command-line interface and a universal app
|
|
4
|
+
example. Releases use the existing Changesets pipeline and npm trusted publishing.
|
|
5
|
+
|
|
6
|
+
## Features
|
|
7
|
+
|
|
8
|
+
- **Multi-runtime support**: Works with Bun, Node.js, and Deno
|
|
9
|
+
- **Universal testing**: Uses [test-anywhere](https://github.com/link-foundation/test-anywhere) for cross-runtime tests
|
|
10
|
+
- **Automated releases**: Changesets-based versioning with GitHub Actions
|
|
11
|
+
- **Optional Docker Hub publishing**: Docker images can be published after the matching npm version is visible
|
|
12
|
+
- **Universal app example**: React UI for the package API with GitHub Pages, Electron, and Capacitor build paths
|
|
13
|
+
- **Code quality**: ESLint + Prettier with pre-commit hooks via Husky
|
|
14
|
+
- **Package manager agnostic**: Works with bun, npm, yarn, pnpm, and deno
|
|
15
|
+
- **Broken link checks**: Automated link validation with [lychee](https://github.com/lycheeverse/lychee-action) and Web Archive fallback suggestions
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
### Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install @link-foundation/universal-translator
|
|
23
|
+
npx @link-foundation/universal-translator --version
|
|
24
|
+
npx @link-foundation/universal-translator add 2 3
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
These registry commands require the first release to have been published. For
|
|
28
|
+
checkout-based use before publication, run `node bin/universal-translator.js --version`.
|
|
29
|
+
|
|
30
|
+
### Development
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Install dependencies
|
|
34
|
+
bun install
|
|
35
|
+
|
|
36
|
+
# Run tests
|
|
37
|
+
bun test --timeout 30000
|
|
38
|
+
|
|
39
|
+
# Or with other runtimes:
|
|
40
|
+
npm test
|
|
41
|
+
deno test -A --parallel
|
|
42
|
+
|
|
43
|
+
# Lint code
|
|
44
|
+
bun run lint
|
|
45
|
+
|
|
46
|
+
# Format code
|
|
47
|
+
bun run format
|
|
48
|
+
|
|
49
|
+
# Check all (lint + format + file size)
|
|
50
|
+
bun run check
|
|
51
|
+
|
|
52
|
+
# Build the universal React example app
|
|
53
|
+
npm install --prefix examples/universal-app
|
|
54
|
+
npm run example:web:build
|
|
55
|
+
npm run example:desktop:package
|
|
56
|
+
|
|
57
|
+
# Try the CLI locally
|
|
58
|
+
node bin/universal-translator.js add 2 3
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Project Structure
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
.
|
|
65
|
+
├── .changeset/ # Changeset configuration
|
|
66
|
+
├── .github/workflows/ # GitHub Actions CI/CD
|
|
67
|
+
├── .husky/ # Git hooks (pre-commit)
|
|
68
|
+
├── examples/ # Usage examples
|
|
69
|
+
│ └── universal-app/ # React + GitHub Pages + Electron + Capacitor app
|
|
70
|
+
├── scripts/ # Build and release scripts
|
|
71
|
+
├── src/ # Source code
|
|
72
|
+
│ ├── index.js # Main entry point
|
|
73
|
+
│ └── index.d.ts # TypeScript definitions
|
|
74
|
+
├── tests/ # Test files
|
|
75
|
+
├── .eslintrc.js # ESLint configuration
|
|
76
|
+
├── .prettierrc # Prettier configuration
|
|
77
|
+
├── bunfig.toml # Bun configuration
|
|
78
|
+
├── deno.json # Deno configuration
|
|
79
|
+
└── package.json # Node.js package manifest
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Design Choices
|
|
83
|
+
|
|
84
|
+
### Multi-Runtime Support
|
|
85
|
+
|
|
86
|
+
This template is designed to work seamlessly with all major JavaScript runtimes:
|
|
87
|
+
|
|
88
|
+
- **Bun**: Primary runtime with highest performance, uses native test support (`bun test`)
|
|
89
|
+
- **Node.js**: Alternative runtime, uses built-in test runner (`node --test`)
|
|
90
|
+
- **Deno**: Secure runtime with built-in TypeScript support (`deno test`)
|
|
91
|
+
|
|
92
|
+
The [test-anywhere](https://github.com/link-foundation/test-anywhere) framework provides a unified testing API that works identically across all runtimes.
|
|
93
|
+
|
|
94
|
+
### Package Manager Agnostic
|
|
95
|
+
|
|
96
|
+
While `package.json` is the source of truth for dependencies, the template supports:
|
|
97
|
+
|
|
98
|
+
- **bun**: Primary choice, uses `bun.lockb`
|
|
99
|
+
- **npm**: Uses `package-lock.json`
|
|
100
|
+
- **yarn**: Uses `yarn.lock`
|
|
101
|
+
- **pnpm**: Uses `pnpm-lock.yaml`
|
|
102
|
+
- **deno**: Uses `deno.json` for configuration
|
|
103
|
+
|
|
104
|
+
Note: `package-lock.json` is not committed by default to allow any package manager.
|
|
105
|
+
|
|
106
|
+
### Universal App Example
|
|
107
|
+
|
|
108
|
+
The template includes `examples/universal-app`, a Vite React app that imports
|
|
109
|
+
`add` and `multiply` from `src/index.js` and renders a visual calculator UI.
|
|
110
|
+
The same static build is used by:
|
|
111
|
+
|
|
112
|
+
- GitHub Pages (`npm run example:web:build`)
|
|
113
|
+
- Electron desktop packaging (`npm run example:desktop:package`)
|
|
114
|
+
- Capacitor Android/iOS sync (`npm run example:mobile:sync`)
|
|
115
|
+
|
|
116
|
+
The example app has its own `package.json` and lockfile so template users can
|
|
117
|
+
opt into the frontend stack without adding React, Electron, or Capacitor to the
|
|
118
|
+
library package itself.
|
|
119
|
+
|
|
120
|
+
See [examples/universal-app/README.md](examples/universal-app/README.md) for
|
|
121
|
+
local web, desktop, Android, and iOS testing instructions.
|
|
122
|
+
|
|
123
|
+
### Code Quality
|
|
124
|
+
|
|
125
|
+
- **ESLint**: Configured with recommended rules + Prettier integration
|
|
126
|
+
- **Prettier**: Consistent code formatting
|
|
127
|
+
- **Husky + lint-staged**: Pre-commit hooks ensure code quality
|
|
128
|
+
- **File size limit**: Files must stay under 1500 lines for maintainability (enforced via ESLint and CI)
|
|
129
|
+
|
|
130
|
+
### Release Workflow
|
|
131
|
+
|
|
132
|
+
The release workflow uses [Changesets](https://github.com/changesets/changesets) for version management:
|
|
133
|
+
|
|
134
|
+
1. **Creating a changeset**: Run `bun run changeset` to document changes
|
|
135
|
+
2. **PR validation**: CI checks for valid changeset in each PR
|
|
136
|
+
3. **Automated versioning**: Merging to `main` triggers version bump
|
|
137
|
+
4. **npm publishing**: Automated via OIDC trusted publishing (no tokens needed)
|
|
138
|
+
5. **Optional Docker Hub publishing**: When configured, waits for the exact npm version and tags the Docker image with that version
|
|
139
|
+
6. **GitHub releases**: Auto-created with formatted release notes
|
|
140
|
+
|
|
141
|
+
#### First release and trusted publisher
|
|
142
|
+
|
|
143
|
+
The npm package name is `@link-foundation/universal-translator`. The repository must match the
|
|
144
|
+
package's `repository.url`: `https://github.com/link-foundation/universal-translator`.
|
|
145
|
+
The existing `.github/workflows/release.yml` is the publishing workflow for both
|
|
146
|
+
automated and manual releases; both publishing jobs grant `id-token: write`
|
|
147
|
+
and install npm with trusted publishing support.
|
|
148
|
+
|
|
149
|
+
To bootstrap an unpublished package with the existing token fallback, configure
|
|
150
|
+
repository secret `NPM_TOKEN` with a granular token that can create and publish
|
|
151
|
+
this public package (including bypass 2FA permission). The workflow passes it as
|
|
152
|
+
`NODE_AUTH_TOKEN`. Merge this PR and allow the pending changesets to produce the
|
|
153
|
+
first version through the normal release process.
|
|
154
|
+
|
|
155
|
+
In the npm package settings, attach a GitHub Actions trusted publisher with:
|
|
156
|
+
|
|
157
|
+
| Field | Value |
|
|
158
|
+
| -------------------- | ---------------------- |
|
|
159
|
+
| Organization or user | `link-foundation` |
|
|
160
|
+
| Repository | `universal-translator` |
|
|
161
|
+
| Workflow filename | `release.yml` |
|
|
162
|
+
| Environment | Leave empty |
|
|
163
|
+
| Permission | Allow `npm publish` |
|
|
164
|
+
|
|
165
|
+
Follow the [npm trusted publishing instructions](https://docs.npmjs.com/trusted-publishers/)
|
|
166
|
+
for account setup. After attaching the publisher, remove the bootstrap token and
|
|
167
|
+
verify that Release Preflight reports a successful package-specific OIDC exchange.
|
|
168
|
+
The preflight reports missing permissions on PRs and fails explicitly on `main`
|
|
169
|
+
until publishing is configured.
|
|
170
|
+
|
|
171
|
+
Verify the released artifact from a clean directory:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
npm view @link-foundation/universal-translator version
|
|
175
|
+
npx --yes @link-foundation/universal-translator --version
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The release workflow also installs the exact published version and tests its
|
|
179
|
+
library and CLI entry points. See [release verification](docs/issue-2-release.md)
|
|
180
|
+
for the implementation checklist and remaining account-level setup.
|
|
181
|
+
|
|
182
|
+
#### Manual Releases
|
|
183
|
+
|
|
184
|
+
Two manual release modes are available via GitHub Actions:
|
|
185
|
+
|
|
186
|
+
- **Instant release**: Immediately bump version and publish
|
|
187
|
+
- **Changeset PR**: Create a PR with changeset for review
|
|
188
|
+
|
|
189
|
+
### CI/CD Pipeline
|
|
190
|
+
|
|
191
|
+
The GitHub Actions workflow (`.github/workflows/release.yml`) implements a fast-fail pipeline:
|
|
192
|
+
|
|
193
|
+
**Fast checks** (~7-30s each, run first for fastest feedback):
|
|
194
|
+
|
|
195
|
+
1. **Test compilation**: Syntax-checks all `.mjs` files with `node --check`
|
|
196
|
+
2. **Lint, format & secrets scan**: ESLint, Prettier, jscpd, and [secretlint](https://github.com/secretlint/secretlint) for credential leak detection
|
|
197
|
+
3. **File line limits**: Enforces the 1500-line limit on JavaScript (`.js`, `.mjs`, `.cjs`) and Markdown (`.md`) files plus `release.yml`
|
|
198
|
+
4. **Changeset check**: Validates PR has exactly one changeset (added by that PR)
|
|
199
|
+
5. **Version check**: Blocks manual version changes in `package.json`
|
|
200
|
+
6. **Documentation validation**: Checks required doc files (doc line limits are enforced by the file line limits check)
|
|
201
|
+
|
|
202
|
+
**Slow checks** (only run after all fast checks pass):
|
|
203
|
+
|
|
204
|
+
7. **Test matrix**: 3 runtimes × 3 OS = 9 test combinations
|
|
205
|
+
8. **Broken link checks**: Validates all links in Markdown/HTML files (separate workflow)
|
|
206
|
+
|
|
207
|
+
**Release** (on merge to main):
|
|
208
|
+
|
|
209
|
+
9. **Changeset merge**: Combines multiple pending changesets at release time
|
|
210
|
+
10. **Release**: Automated versioning and npm publishing
|
|
211
|
+
11. **Optional Docker publish**: Publishes Docker Hub `latest` and npm-version tags after the npm package is visible
|
|
212
|
+
|
|
213
|
+
#### Reasonable Timeouts
|
|
214
|
+
|
|
215
|
+
Every CI job declares an explicit `timeout-minutes` so hung steps fail
|
|
216
|
+
in minutes instead of reaching the GitHub Actions default of six hours.
|
|
217
|
+
Fast checks use 5-10 minute caps, release jobs use 50 minutes, and the
|
|
218
|
+
link checker uses 10 minutes for external network variance.
|
|
219
|
+
|
|
220
|
+
That cap is a backstop, never the deadline: GitHub reports a job it
|
|
221
|
+
kills as **cancelled**, not **failed**. Long steps therefore own an
|
|
222
|
+
explicit budget via `scripts/run-with-budget-warning.sh`, which warns at
|
|
223
|
+
70% of the budget and fails the step with exit code 124 when it expires.
|
|
224
|
+
See [CI-TIMEOUT-BUDGETS.md](docs/CI-TIMEOUT-BUDGETS.md).
|
|
225
|
+
|
|
226
|
+
Individual tests are also capped inside supported runners:
|
|
227
|
+
`npm test` runs `node --test --test-timeout=30000`, and the CI Bun
|
|
228
|
+
runner uses `bun test --timeout 30000`. Both bound a _single test_, not
|
|
229
|
+
the suite, which is why the suite budget above exists. Deno does not
|
|
230
|
+
provide a single global per-test timeout flag, so Deno tests are
|
|
231
|
+
protected by their step budget and the matrix job backstop.
|
|
232
|
+
|
|
233
|
+
See [BEST-PRACTICES.md](docs/BEST-PRACTICES.md) for detailed explanations of each practice.
|
|
234
|
+
|
|
235
|
+
#### Robust Changeset Handling
|
|
236
|
+
|
|
237
|
+
The CI/CD pipeline is designed to handle concurrent PRs gracefully:
|
|
238
|
+
|
|
239
|
+
- **PR Validation**: Only validates changesets **added by the current PR**, not pre-existing ones from other merged PRs. This prevents false failures when multiple PRs merge before a release cycle completes.
|
|
240
|
+
|
|
241
|
+
- **Release-time Merging**: If multiple changesets exist when releasing, they are automatically merged into a single changeset with:
|
|
242
|
+
- The highest version bump type (major > minor > patch)
|
|
243
|
+
- All descriptions preserved in chronological order
|
|
244
|
+
|
|
245
|
+
This design decouples PR validation from the need to pull changes from the default branch, reducing conflicts and ensuring that even if CI/CD fails, all unpublished changesets will still get published when the error is resolved.
|
|
246
|
+
|
|
247
|
+
### Deploying the example app
|
|
248
|
+
|
|
249
|
+
The `example-app.yml` workflow deploys the universal example app to GitHub
|
|
250
|
+
Pages on every push to `main`. Before the first run on `main` in a new
|
|
251
|
+
repository created from this template, open **Settings → Pages** and set
|
|
252
|
+
**Source = GitHub Actions**. This is a one-time manual step and cannot be
|
|
253
|
+
configured from a workflow because the Pages source defaults to
|
|
254
|
+
_Deploy from a branch_. Without it, the `pages-deploy` job fails on
|
|
255
|
+
`actions/deploy-pages` with `Get Pages site failed` /
|
|
256
|
+
`Failed to create deployment`. After flipping the source, the workflow
|
|
257
|
+
provisions the Pages site on its first run.
|
|
258
|
+
|
|
259
|
+
### Auto-regenerated preview screenshots
|
|
260
|
+
|
|
261
|
+
The same `example-app.yml` workflow contains a `preview-regen` job that boots
|
|
262
|
+
the built example app in a headless Chromium via
|
|
263
|
+
[`browser-commander`](https://www.npmjs.com/package/browser-commander) +
|
|
264
|
+
Playwright and writes fresh screenshots to
|
|
265
|
+
`docs/screenshots/example-app/example-app-{locale}-{theme}.png` on every
|
|
266
|
+
push to `main` (and on `workflow_dispatch`). Any drift is committed back to
|
|
267
|
+
`main` so README/site images never go stale between releases. Screenshot-only
|
|
268
|
+
pushes do not match this workflow's path filter, while a protected-branch
|
|
269
|
+
fallback PR remains eligible for its required checks. The job runs in the
|
|
270
|
+
official Playwright container with the browser already installed, avoiding CI
|
|
271
|
+
stalls from live Chromium downloads.
|
|
272
|
+
|
|
273
|
+
The same script is available locally:
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
npm install --prefix examples/universal-app
|
|
277
|
+
npm run example:web:preview-images
|
|
278
|
+
# Verbose probe of <html data-theme>, <html lang>, and PNG signatures:
|
|
279
|
+
PREVIEW_VERBOSE=1 npm run example:web:preview-images
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
The matrix defaults to `{en, ru} × {light, dark}`. The shipped example app
|
|
283
|
+
has no localization or theme toggle yet, so every cell currently renders
|
|
284
|
+
the same UI — when a fork adds either, the matrix produces real per-cell
|
|
285
|
+
variants without script edits.
|
|
286
|
+
|
|
287
|
+
### Broken Link Checker
|
|
288
|
+
|
|
289
|
+
The link checker workflow (`.github/workflows/links.yml`) validates all links in Markdown and HTML files:
|
|
290
|
+
|
|
291
|
+
1. **Detection**: Uses [lychee](https://github.com/lycheeverse/lychee-action) to scan all `*.md` and `*.html` files
|
|
292
|
+
2. **Web Archive fallback**: For any broken links found, automatically checks the [Wayback Machine](https://web.archive.org) for archived versions
|
|
293
|
+
3. **Actionable suggestions**: Reports one of three outcomes for each broken link:
|
|
294
|
+
- **Archived**: Suggests the Web Archive URL as a replacement
|
|
295
|
+
- **Not archived**: Clearly reports the link is unrecoverable
|
|
296
|
+
4. **Scheduled checks**: Runs weekly to catch links that break over time (even if no files changed)
|
|
297
|
+
5. **Issue creation**: On scheduled runs, creates a GitHub Issue with the full broken links report
|
|
298
|
+
|
|
299
|
+
Add regex patterns to `.lycheeignore` to exclude URLs from checks (e.g., local dev URLs, example.com, known rate-limited sites).
|
|
300
|
+
|
|
301
|
+
## Configuration
|
|
302
|
+
|
|
303
|
+
### Package Identity
|
|
304
|
+
|
|
305
|
+
`package.json` and `package-lock.json` use `@link-foundation/universal-translator`. The installed
|
|
306
|
+
command is `universal-translator`, provided by `bin/universal-translator.js`.
|
|
307
|
+
Release scripts derive the package name from `package.json` at runtime.
|
|
308
|
+
|
|
309
|
+
### Protected-Branch Release Pull Requests
|
|
310
|
+
|
|
311
|
+
If `main` requires pull requests and the `Pipeline Status` check, the release
|
|
312
|
+
and instant-release jobs can use their built-in `GITHUB_TOKEN` to open a release
|
|
313
|
+
PR. Enable **Allow GitHub Actions to create and approve pull requests** in
|
|
314
|
+
repository Actions settings. The helper verifies that the version commit is a
|
|
315
|
+
direct child of the validated workflow SHA and contains only package metadata
|
|
316
|
+
and consumed changesets. It then creates a successful `Pipeline Status` check
|
|
317
|
+
on that exact commit, linked to the validating run, waits for every required
|
|
318
|
+
check, and merges the PR only after they pass. The release jobs alone receive
|
|
319
|
+
`checks: write`. Set `RELEASE_METADATA_PATHS` to a comma-separated list of
|
|
320
|
+
additional exact metadata paths for other package layouts.
|
|
321
|
+
|
|
322
|
+
An optional `RELEASE_PR_TOKEN` secret keeps the existing dedicated-token path
|
|
323
|
+
and takes precedence when set. Give that actor Contents and Pull requests write
|
|
324
|
+
access and Checks read access. The manual changeset-PR and generated-preview
|
|
325
|
+
paths still require the dedicated token. A short-lived GitHub App installation
|
|
326
|
+
token can be wired to the same inputs instead of a PAT.
|
|
327
|
+
|
|
328
|
+
### Optional Docker Hub Publishing
|
|
329
|
+
|
|
330
|
+
Docker publishing is disabled by default. To enable it for a project that ships
|
|
331
|
+
a Docker image, add a `Dockerfile` and configure these GitHub Actions settings:
|
|
332
|
+
|
|
333
|
+
| Setting | Type | Description |
|
|
334
|
+
| -------------------- | ------------------ | ------------------------------------------------------------------------------------- |
|
|
335
|
+
| `DOCKERHUB_IMAGE` | Variable | Docker Hub image name, for example `namespace/image`. This enables Docker publishing. |
|
|
336
|
+
| `DOCKERHUB_USERNAME` | Variable | Docker Hub username used by `docker/login-action`. |
|
|
337
|
+
| `DOCKERHUB_TOKEN` | Secret | Docker Hub access token used for registry authentication. |
|
|
338
|
+
| `DOCKER_CONTEXT` | Variable, optional | Docker build context. Defaults to `.`. |
|
|
339
|
+
| `DOCKERFILE` | Variable, optional | Dockerfile path. Defaults to `./Dockerfile`. |
|
|
340
|
+
|
|
341
|
+
When enabled, the release workflow waits until the exact published npm version
|
|
342
|
+
is visible in the npm registry, then publishes Docker Hub tags for `latest` and
|
|
343
|
+
that same version. The Docker build also receives `NPM_PACKAGE_VERSION` as a
|
|
344
|
+
build argument so Dockerfiles can install the matching published package.
|
|
345
|
+
|
|
346
|
+
### ESLint Rules
|
|
347
|
+
|
|
348
|
+
Customize ESLint in `eslint.config.js`. Current configuration:
|
|
349
|
+
|
|
350
|
+
- ES Modules support
|
|
351
|
+
- Prettier integration
|
|
352
|
+
- No console restrictions (common in CLI tools)
|
|
353
|
+
- Strict equality enforcement
|
|
354
|
+
- Async/await best practices
|
|
355
|
+
- **Strict unused variables rule**: No exceptions - all unused variables, arguments, and caught errors must be removed (no `_` prefix exceptions)
|
|
356
|
+
|
|
357
|
+
### Prettier Options
|
|
358
|
+
|
|
359
|
+
Configured in `.prettierrc`:
|
|
360
|
+
|
|
361
|
+
- Single quotes
|
|
362
|
+
- Semicolons
|
|
363
|
+
- 2-space indentation
|
|
364
|
+
- 80-character line width
|
|
365
|
+
- ES5 trailing commas
|
|
366
|
+
- LF line endings
|
|
367
|
+
|
|
368
|
+
## Scripts Reference
|
|
369
|
+
|
|
370
|
+
| Script | Description |
|
|
371
|
+
| ------------------------------------ | ----------------------------------------------------- |
|
|
372
|
+
| `bun test --timeout 30000` | Run tests with Bun and a 30s per-test cap |
|
|
373
|
+
| `npm test` | Run tests with Node.js and a 30s per-test cap |
|
|
374
|
+
| `bun run lint` | Check code with ESLint |
|
|
375
|
+
| `bun run lint:fix` | Fix ESLint issues automatically |
|
|
376
|
+
| `bun run format` | Format code with Prettier |
|
|
377
|
+
| `bun run format:check` | Check formatting without changing files |
|
|
378
|
+
| `bun run check` | Run all checks (lint + format) |
|
|
379
|
+
| `npm run example:web:dev` | Start the universal app Vite dev server |
|
|
380
|
+
| `npm run example:web:build` | Build the universal app static web bundle |
|
|
381
|
+
| `npm run example:web:preview-images` | Regenerate preview screenshots via browser-commander |
|
|
382
|
+
| `npm run example:desktop:package` | Package the Electron desktop app locally |
|
|
383
|
+
| `npm run example:mobile:sync` | Build and sync the app bundle into Capacitor projects |
|
|
384
|
+
| `bun run changeset` | Create a new changeset |
|
|
385
|
+
|
|
386
|
+
## Contributing
|
|
387
|
+
|
|
388
|
+
See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed contribution guidelines.
|
|
389
|
+
|
|
390
|
+
Quick steps:
|
|
391
|
+
|
|
392
|
+
1. Fork the repository
|
|
393
|
+
2. Create a feature branch: `git checkout -b feature/my-feature`
|
|
394
|
+
3. Make your changes
|
|
395
|
+
4. Create a changeset: `bun run changeset`
|
|
396
|
+
5. Commit your changes (pre-commit hooks will run automatically)
|
|
397
|
+
6. Push and create a Pull Request
|
|
398
|
+
|
|
399
|
+
## Best Practices
|
|
400
|
+
|
|
401
|
+
This template implements CI/CD best practices for AI-driven development. See [BEST-PRACTICES.md](docs/BEST-PRACTICES.md) for details on:
|
|
402
|
+
|
|
403
|
+
- File size limits for AI readability
|
|
404
|
+
- Automated formatting and linting
|
|
405
|
+
- Multi-runtime and cross-platform testing
|
|
406
|
+
- Changeset-based versioning
|
|
407
|
+
- Concurrency control for CI/CD pipelines
|
|
408
|
+
|
|
409
|
+
## License
|
|
410
|
+
|
|
411
|
+
[Unlicense](LICENSE) - Public Domain
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { readFileSync, realpathSync } from 'node:fs';
|
|
4
|
+
import { fileURLToPath, URL } from 'node:url';
|
|
5
|
+
|
|
6
|
+
import { add, multiply } from '../src/index.js';
|
|
7
|
+
|
|
8
|
+
const COMMANDS = {
|
|
9
|
+
add,
|
|
10
|
+
multiply,
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
function usage() {
|
|
14
|
+
return [
|
|
15
|
+
'Usage: universal-translator <command> <left> <right>',
|
|
16
|
+
'',
|
|
17
|
+
'Commands:',
|
|
18
|
+
' add Add two numbers',
|
|
19
|
+
' multiply Multiply two numbers',
|
|
20
|
+
'',
|
|
21
|
+
'Options:',
|
|
22
|
+
' --help Show this help',
|
|
23
|
+
' --version Show package version',
|
|
24
|
+
].join('\n');
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function readVersion() {
|
|
28
|
+
const packageUrl = new URL('../package.json', import.meta.url);
|
|
29
|
+
const packageJson = JSON.parse(readFileSync(packageUrl, 'utf8'));
|
|
30
|
+
return packageJson.version;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function parseNumber(value, label) {
|
|
34
|
+
const parsed = Number(value);
|
|
35
|
+
|
|
36
|
+
if (!Number.isFinite(parsed)) {
|
|
37
|
+
throw new Error(`${label} must be a finite number`);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
return parsed;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function runCli(
|
|
44
|
+
argv,
|
|
45
|
+
{ stderr = console.error, stdout = console.log } = {}
|
|
46
|
+
) {
|
|
47
|
+
const [command, left, right] = argv;
|
|
48
|
+
|
|
49
|
+
if (!command || command === '--help' || command === '-h') {
|
|
50
|
+
stdout(usage());
|
|
51
|
+
return 0;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
if (command === '--version' || command === '-v') {
|
|
55
|
+
stdout(readVersion());
|
|
56
|
+
return 0;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const operation = COMMANDS[command];
|
|
60
|
+
|
|
61
|
+
if (!operation) {
|
|
62
|
+
stderr(`Unknown command: ${command}`);
|
|
63
|
+
stderr(usage());
|
|
64
|
+
return 1;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
try {
|
|
68
|
+
const leftNumber = parseNumber(left, 'left');
|
|
69
|
+
const rightNumber = parseNumber(right, 'right');
|
|
70
|
+
stdout(String(operation(leftNumber, rightNumber)));
|
|
71
|
+
return 0;
|
|
72
|
+
} catch (error) {
|
|
73
|
+
stderr(error.message);
|
|
74
|
+
return 1;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function isCliEntryPoint() {
|
|
79
|
+
if (!process.argv[1]) {
|
|
80
|
+
return false;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
try {
|
|
84
|
+
return (
|
|
85
|
+
realpathSync(process.argv[1]) ===
|
|
86
|
+
realpathSync(fileURLToPath(import.meta.url))
|
|
87
|
+
);
|
|
88
|
+
} catch {
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
if (isCliEntryPoint()) {
|
|
94
|
+
process.exitCode = runCli(process.argv.slice(2));
|
|
95
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,91 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@link-foundation/universal-translator",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.11.31",
|
|
4
|
+
"description": "A JavaScript/TypeScript package template for AI-driven development",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "src/index.js",
|
|
7
|
+
"types": "src/index.d.ts",
|
|
8
|
+
"bin": {
|
|
9
|
+
"universal-translator": "./bin/universal-translator.js"
|
|
10
|
+
},
|
|
11
|
+
"files": [
|
|
12
|
+
"bin/",
|
|
13
|
+
"src/",
|
|
14
|
+
"CHANGELOG.md",
|
|
15
|
+
"LICENSE",
|
|
16
|
+
"README.md"
|
|
17
|
+
],
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./src/index.d.ts",
|
|
21
|
+
"import": "./src/index.js"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"scripts": {
|
|
25
|
+
"test": "node --test --test-timeout=30000 tests/*.test.js",
|
|
26
|
+
"lint": "node scripts/lint.mjs",
|
|
27
|
+
"lint:all": "eslint .",
|
|
28
|
+
"lint:fix": "eslint . --fix",
|
|
29
|
+
"format": "prettier --write .",
|
|
30
|
+
"format:check": "prettier --check .",
|
|
31
|
+
"check:duplication": "jscpd .",
|
|
32
|
+
"check": "npm run lint && npm run format:check && npm run check:duplication",
|
|
33
|
+
"example:web:dev": "npm --prefix examples/universal-app run dev",
|
|
34
|
+
"example:web:build": "npm --prefix examples/universal-app run build",
|
|
35
|
+
"example:web:preview": "npm --prefix examples/universal-app run preview",
|
|
36
|
+
"example:web:preview-images": "node scripts/update-preview-images.mjs",
|
|
37
|
+
"example:desktop:package": "npm --prefix examples/universal-app run desktop:package",
|
|
38
|
+
"example:desktop:make": "npm --prefix examples/universal-app run desktop:make",
|
|
39
|
+
"example:mobile:sync": "npm --prefix examples/universal-app run mobile:sync",
|
|
40
|
+
"prepare": "node scripts/install-git-hooks.mjs",
|
|
41
|
+
"changeset": "changeset",
|
|
42
|
+
"changeset:version": "node scripts/changeset-version.mjs",
|
|
43
|
+
"changeset:publish": "changeset publish",
|
|
44
|
+
"changeset:status": "changeset status --since=origin/main"
|
|
45
|
+
},
|
|
46
|
+
"keywords": [
|
|
47
|
+
"template",
|
|
48
|
+
"javascript",
|
|
49
|
+
"typescript",
|
|
50
|
+
"ai-driven"
|
|
51
|
+
],
|
|
52
|
+
"author": "",
|
|
53
|
+
"license": "Unlicense",
|
|
54
|
+
"devEngines": {
|
|
55
|
+
"packageManager": {
|
|
56
|
+
"name": "npm"
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"publishConfig": {
|
|
60
|
+
"access": "public"
|
|
61
|
+
},
|
|
62
|
+
"repository": {
|
|
63
|
+
"type": "git",
|
|
64
|
+
"url": "git+https://github.com/link-foundation/universal-translator.git"
|
|
65
|
+
},
|
|
66
|
+
"engines": {
|
|
67
|
+
"node": ">=20.0.0"
|
|
68
|
+
},
|
|
69
|
+
"devDependencies": {
|
|
70
|
+
"@changesets/cli": "^3.0.3",
|
|
71
|
+
"eslint": "^9.38.0",
|
|
72
|
+
"eslint-config-prettier": "^10.1.8",
|
|
73
|
+
"eslint-plugin-prettier": "^5.5.4",
|
|
74
|
+
"husky": "^9.1.7",
|
|
75
|
+
"jscpd": "^5.4.0",
|
|
76
|
+
"lint-staged": "^16.4.0",
|
|
77
|
+
"prettier": "^3.6.2",
|
|
78
|
+
"test-anywhere": "^0.8.48"
|
|
79
|
+
},
|
|
80
|
+
"lint-staged": {
|
|
81
|
+
"*.{js,mjs,cjs}": [
|
|
82
|
+
"eslint --fix --max-warnings 0 --no-warn-ignored",
|
|
83
|
+
"prettier --write",
|
|
84
|
+
"prettier --check"
|
|
85
|
+
],
|
|
86
|
+
"*.md": [
|
|
87
|
+
"prettier --write",
|
|
88
|
+
"prettier --check"
|
|
89
|
+
]
|
|
90
|
+
}
|
|
91
|
+
}
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example module type definitions
|
|
3
|
+
* Replace this with your actual type definitions
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Adds two numbers
|
|
8
|
+
* @param a - First number
|
|
9
|
+
* @param b - Second number
|
|
10
|
+
* @returns Sum of a and b
|
|
11
|
+
*/
|
|
12
|
+
export declare const add: (a: number, b: number) => number;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Multiplies two numbers
|
|
16
|
+
* @param a - First number
|
|
17
|
+
* @param b - Second number
|
|
18
|
+
* @returns Product of a and b
|
|
19
|
+
*/
|
|
20
|
+
export declare const multiply: (a: number, b: number) => number;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Delays execution for specified milliseconds
|
|
24
|
+
* @param ms - Milliseconds to wait
|
|
25
|
+
* @returns Promise that resolves after the delay
|
|
26
|
+
*/
|
|
27
|
+
export declare const delay: (ms: number) => Promise<void>;
|
package/src/index.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example module entry point
|
|
3
|
+
* Replace this with your actual implementation
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Example function that adds two numbers
|
|
8
|
+
* @param {number} a - First number
|
|
9
|
+
* @param {number} b - Second number
|
|
10
|
+
* @returns {number} Sum of a and b
|
|
11
|
+
*/
|
|
12
|
+
export const add = (a, b) => a + b;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Example function that multiplies two numbers
|
|
16
|
+
* @param {number} a - First number
|
|
17
|
+
* @param {number} b - Second number
|
|
18
|
+
* @returns {number} Product of a and b
|
|
19
|
+
*/
|
|
20
|
+
export const multiply = (a, b) => a * b;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Example async function
|
|
24
|
+
* @param {number} ms - Milliseconds to wait
|
|
25
|
+
* @returns {Promise<void>}
|
|
26
|
+
*/
|
|
27
|
+
export const delay = (ms) =>
|
|
28
|
+
new Promise((resolve) => globalThis.setTimeout(resolve, ms));
|