@link-foundation/universal-translator 0.0.0-stage → 0.11.32

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 ADDED
@@ -0,0 +1,546 @@
1
+ # Changelog
2
+
3
+ ## 0.11.32
4
+
5
+ ### Patch Changes
6
+
7
+ - Run repository-wide workflow audits on all relevant inputs, report unavailable tests with explicit reasons, and exercise fixture coverage under parallel Deno testing. Give npm propagation a 25.5-minute verification window, keep runtime-owned lockfiles quiet, validate lock/config/install-script policies, and avoid duplicate publish output.
8
+
9
+ Pin Changesets release formatting to Prettier and validate versioning on pull requests without publishing credentials. Reject unchanged moves of pending changesets while accepting new replacement fragments, and check both paths of code moves.
10
+
11
+ Make version and changeset validation fail on unavailable Git comparisons, verify npm trusted publishing with a package-specific OIDC exchange, repair release badge detection and commit quoting, and recover missing GitHub releases without another version bump. Correct process survivor reporting, remove a busy-looping test fixture, pin CI scanners and hosted runner images, and exclude experimental and example code from CodeQL.
12
+
13
+ Publish under the `@link-foundation` npm scope because the unscoped name is rejected as too similar to an existing package.
14
+
15
+ Retry transient HTTP link failures with bounded backoff and authenticated GitHub contents fallback, and pin the Bun CI runtime to the supported 1.x line. Refresh vulnerable development dependencies so pipeline security checks can pass.
16
+
17
+ Publish as `@link-foundation/universal-translator` with the matching CLI command, repository metadata, and release verification.
18
+
19
+ ## 0.11.31
20
+
21
+ ### Patch Changes
22
+
23
+ - Fix every open CI correctness and resilience issue in the pipeline: scope the
24
+ Docker buildx cache, retry transient fetch and download failures, make the
25
+ budget wrapper escalate to SIGKILL, add a terminal status gate to every
26
+ workflow with supersede detection, verify the husky install, make the jscpd
27
+ gate analyse real files, guard the package manager declaration, turn on
28
+ command-stream errexit, gate staged formatting before release commits, add
29
+ release-preflight credential checks, and sweep zizmor/actionlint/persisted
30
+ credentials/link-recheck fixes across the workflows.
31
+
32
+ Allow protected releases to use the built-in GitHub Actions token after
33
+ metadata-only attestation, wait through npm registry propagation without
34
+ republishing, and skip deleted changesets during staged formatting checks.
35
+
36
+ Make protected-branch release fallbacks wait for real pull-request checks with
37
+ a dedicated automation token, and pin every Linux CI job to Ubuntu 24.04.
38
+
39
+ Harden CI verdicts, Docker manifest publication, timeout cleanup, broken-link
40
+ rechecks, and contributor-authored workflow logs, and refresh vulnerable
41
+ transitive development dependencies.
42
+
43
+ ## 0.11.30
44
+
45
+ ### Patch Changes
46
+
47
+ - 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.
48
+
49
+ ## 0.11.29
50
+
51
+ ### Patch Changes
52
+
53
+ - 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.
54
+
55
+ `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`.
56
+
57
+ 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.
58
+
59
+ ## 0.11.28
60
+
61
+ ### Patch Changes
62
+
63
+ - 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`.
64
+
65
+ Add a scheduled fail-closed high-severity audit for every committed npm lock.
66
+
67
+ Ignore successful redirects when checking Lychee reports for broken links.
68
+
69
+ 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.
70
+
71
+ Fail the web archive check on lychee errors that have no http(s) URL
72
+
73
+ `scripts/check-web-archive.mjs` only extracted `http(s)` links from the lychee
74
+ report, so errors such as a missing local file or an unresolvable root-relative
75
+ link were silently dropped. When those were the only errors the script printed
76
+ "No broken URLs found" and set `all_archived=true`, masking a failing lychee
77
+ run. The parser now matches the status marker instead of the URL and splits the
78
+ results into archivable URLs and links the Wayback Machine cannot answer; the
79
+ latter are annotated as errors and force `all_archived=false` with exit code 1.
80
+ Adds regression tests over a captured lychee report fixture.
81
+
82
+ 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.
83
+
84
+ Publish Docker images for both amd64 and arm64 using native runners and a multi-architecture manifest.
85
+
86
+ Suppress the reviewed DEP0005 warning from the Docker manifest artifact download step.
87
+
88
+ 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.
89
+
90
+ Give long CI steps their own execution budget so an overrun reports `failure` instead of `cancelled`.
91
+
92
+ Fail broken-link checks until archived replacements are applied to dead links.
93
+
94
+ Load `command-stream` and `lino-arguments` through a shared use-m interop shim so the release scripts work on Node 24.
95
+
96
+ 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`.
97
+
98
+ Report why `scripts/wait-for-npm.mjs` could not confirm a release. The check
99
+ queries the npm registry over HTTP and returns `{ available, status, httpStatus,
100
+ url, error }`, so an HTTP 404 ("not published") is distinguished from an
101
+ unanswered probe (5xx, rate limit, proxy, DNS). Every attempt logs its outcome,
102
+ and an unanswered probe no longer claims the version "did not become available
103
+ on npm" — it says the publish status is unknown and points at the registry URL
104
+ to check. The step also exposes an `npm_check_status` output.
105
+
106
+ ## 0.11.27
107
+
108
+ ### Patch Changes
109
+
110
+ - 53519f1: Report release pipeline timeout cancellations as visible failures on the default branch.
111
+
112
+ ## 0.11.26
113
+
114
+ ### Patch Changes
115
+
116
+ - 328d858: Add CodeQL analysis for JavaScript and GitHub Actions plus high-severity dependency review for pull requests.
117
+
118
+ ## 0.11.25
119
+
120
+ ### Patch Changes
121
+
122
+ - 8af8547: Require successful lint and test quality gates before manual releases can publish.
123
+
124
+ ## 0.11.24
125
+
126
+ ### Patch Changes
127
+
128
+ - dd8a969: Reject unsupported keys in generated workflow concurrency blocks.
129
+
130
+ ## 0.11.23
131
+
132
+ ### Patch Changes
133
+
134
+ - e73716a: Harden workflow inputs, checkout configuration, and deployment concurrency.
135
+
136
+ ## 0.11.22
137
+
138
+ ### Patch Changes
139
+
140
+ - d0b42fa: Keep excluded-directory changes from activating change-gated CI jobs on pull
141
+ requests and direct pushes.
142
+
143
+ ## 0.11.21
144
+
145
+ ### Patch Changes
146
+
147
+ - 5bf9619: Quote the fresh merge base ref to prevent shell word splitting.
148
+
149
+ ## 0.11.20
150
+
151
+ ### Patch Changes
152
+
153
+ - 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.
154
+
155
+ ## 0.11.19
156
+
157
+ ### Patch Changes
158
+
159
+ - 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`.
160
+
161
+ ## 0.11.18
162
+
163
+ ### Patch Changes
164
+
165
+ - 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.
166
+
167
+ ## 0.11.17
168
+
169
+ ### Patch Changes
170
+
171
+ - 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.
172
+
173
+ ## 0.11.16
174
+
175
+ ### Patch Changes
176
+
177
+ - 1349837: Suppress the Git default-branch hint during release workflow checkout.
178
+
179
+ ## 0.11.15
180
+
181
+ ### Patch Changes
182
+
183
+ - 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.
184
+
185
+ ## 0.11.14
186
+
187
+ ### Patch Changes
188
+
189
+ - 63b31c3: Harden generated preview-image pushes against main branch non-fast-forward races.
190
+
191
+ ## 0.11.13
192
+
193
+ ### Patch Changes
194
+
195
+ - Add a warning-level ESLint rule for changelog-style comments and strings.
196
+
197
+ Detect code changes from real merge commits pushed to main with the first-parent
198
+ merge diff while preserving pull request synthetic merge behavior.
199
+
200
+ ## 0.11.12
201
+
202
+ ### Patch Changes
203
+
204
+ - 89fb151: Ignore stray Markdown files when checking for pending changesets.
205
+
206
+ ## 0.11.11
207
+
208
+ ### Patch Changes
209
+
210
+ - d2e3932: Require exact changelog version headers when extracting GitHub release notes.
211
+ - e7356e9: Fail release-time changeset merging when any pending changeset is malformed.
212
+
213
+ ## 0.11.10
214
+
215
+ ### Patch Changes
216
+
217
+ - 9915756: Auto-detect single-language versus `js/` monorepo layouts when naming GitHub
218
+ releases, namespace multi-language JavaScript tags as `js_v<version>`, and
219
+ normalize prefixed tags before linking npm version badges.
220
+
221
+ ## 0.11.9
222
+
223
+ ### Patch Changes
224
+
225
+ - 49a8205: Add a post-publish smoke test that installs the just-published npm package in a clean project and verifies its entry points.
226
+
227
+ ## 0.11.8
228
+
229
+ ### Patch Changes
230
+
231
+ - 391530e: Skip the slow CI test matrix for pull requests that only touch non-code files.
232
+
233
+ ## 0.11.7
234
+
235
+ ### Patch Changes
236
+
237
+ - 674f9ce: Fix npm release path for brand-new packages (issue #77):
238
+ - `publish-to-npm.mjs` now classifies authentication / registry-configuration
239
+ failures (404/401/403, `access token expired`, `ENEEDAUTH`, etc.) as
240
+ non-retryable and fails fast with actionable guidance instead of retrying
241
+ `MAX_RETRIES` times and hiding the real cause behind a generic error.
242
+ - The `release` and `instant-release` publish steps now pass an optional
243
+ `NODE_AUTH_TOKEN` sourced from `secrets.NPM_TOKEN`, providing a first-publish
244
+ bootstrap path. OIDC trusted publishing remains the steady-state mechanism;
245
+ the token is only needed for the very first release of a new package.
246
+
247
+ ## 0.11.6
248
+
249
+ ### Patch Changes
250
+
251
+ - 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).
252
+
253
+ ## 0.11.5
254
+
255
+ ### Patch Changes
256
+
257
+ - 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.
258
+
259
+ ## 0.11.4
260
+
261
+ ### Patch Changes
262
+
263
+ - 35696cc: Cap generated GitHub release notes before creating releases so oversized changelog
264
+ entries link to the full tagged changelog instead of failing GitHub API
265
+ validation.
266
+
267
+ ## 0.11.3
268
+
269
+ ### Patch Changes
270
+
271
+ - 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.
272
+
273
+ ## 0.11.2
274
+
275
+ ### Patch Changes
276
+
277
+ - 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.
278
+
279
+ ## 0.11.1
280
+
281
+ ### Patch Changes
282
+
283
+ - 8cd0d70: Correct CI workflow concurrency and preview failure artifact handling in the template.
284
+
285
+ ## 0.11.0
286
+
287
+ ### Minor Changes
288
+
289
+ - e7025ed: Add a release-time `preview-regen` job to `example-app.yml` and a
290
+ `scripts/update-preview-images.mjs` driver that boot the universal example app
291
+ in a headless Chromium via `browser-commander` + Playwright, capture a
292
+ locale × theme matrix of screenshots into `docs/screenshots/example-app/`, and
293
+ commit any drift back to `main` with `[skip ci]`. Adds the matching
294
+ `npm run example:web:preview-images` script.
295
+
296
+ ## 0.10.2
297
+
298
+ ### Patch Changes
299
+
300
+ - 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.
301
+
302
+ ## 0.10.1
303
+
304
+ ### Patch Changes
305
+
306
+ - ede9f84: Publish the template as the real link-foundation example package and add the globally installable CLI entry point.
307
+
308
+ ## 0.10.0
309
+
310
+ ### Minor Changes
311
+
312
+ - 5a81a7f: Add a universal React example app with GitHub Pages, Electron desktop, and Capacitor mobile build paths.
313
+
314
+ ## 0.9.0
315
+
316
+ ### Minor Changes
317
+
318
+ - f23283c: Add an optional Docker Hub publishing path that waits for the exact npm
319
+ package version before tagging Docker images.
320
+
321
+ ## 0.8.6
322
+
323
+ ### Patch Changes
324
+
325
+ - acccf75: Format GitHub release names as human-readable `[Language] x.y.z` titles while keeping prefixed tag names unchanged.
326
+
327
+ ## 0.8.5
328
+
329
+ ### Patch Changes
330
+
331
+ - Fail GitHub release creation on unexpected gh api errors and clearly skip releases that already exist.
332
+
333
+ Enforce npm and Node.js minimum versions for trusted publishing setup and resolve a supported npm 11 tarball for fallback installs.
334
+
335
+ ## 0.8.4
336
+
337
+ ### Patch Changes
338
+
339
+ - 031f7cd: Add explicit CI job timeouts and per-test runner timeout limits.
340
+
341
+ ## 0.8.3
342
+
343
+ ### Patch Changes
344
+
345
+ - bdaa4b7: Derive release script package names from package.json instead of template placeholders.
346
+
347
+ ## 0.8.2
348
+
349
+ ### Patch Changes
350
+
351
+ - d179bb7: Add warning annotations for files approaching the CI file line limit.
352
+
353
+ ## 0.8.1
354
+
355
+ ### Patch Changes
356
+
357
+ - f0c69af: Normalize language-prefixed release tags before building npm shields.io badge URLs.
358
+
359
+ ## 0.8.0
360
+
361
+ ### Minor Changes
362
+
363
+ - 3e45a9c: Add `--tag-prefix` option to release scripts for multi-language repos
364
+
365
+ 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`).
366
+
367
+ ## 0.7.3
368
+
369
+ ### Patch Changes
370
+
371
+ - ae2cc9a: Add self-healing release mechanism that checks npm registry for unpublished versions
372
+
373
+ ## 0.7.2
374
+
375
+ ### Patch Changes
376
+
377
+ - 9126e16: fix: npm upgrade fallbacks and Node.js 24.x upgrade for CI/CD
378
+ - Upgrade Node.js from 20.x to 24.x in all workflow files (avoids broken npm in Node.js 22.22.2)
379
+ - Add 4-strategy fallback chain to setup-npm.mjs (standard, curl tarball, npx, corepack)
380
+ - Update GitHub Actions to latest versions (checkout v6, setup-node v6, create-pull-request v8)
381
+ - Add case study documentation for issue #33
382
+
383
+ ## 0.7.1
384
+
385
+ ### Patch Changes
386
+
387
+ - 6916409: Use per-commit diff instead of full-PR diff for CI change detection
388
+
389
+ ## 0.7.0
390
+
391
+ ### Minor Changes
392
+
393
+ - 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
394
+
395
+ ## 0.6.0
396
+
397
+ ### Minor Changes
398
+
399
+ - 8961862: Add automated broken link checker with Web Archive fallback suggestions
400
+ - Add `.github/workflows/links.yml` with lychee-action for link checking in Markdown and HTML files
401
+ - Add `scripts/check-web-archive.mjs` to check broken links against the Wayback Machine API
402
+ - Add `.lycheeignore` for excluding known false-positive URLs (localhost, example.com, etc.)
403
+ - Update `README.md` to document the broken link checker feature
404
+ - Scheduled weekly check (Mondays at 09:00 UTC) to catch links that break over time
405
+ - On PRs, broken links with no Web Archive fallback will fail the check
406
+ - For broken links that have archived versions, provides actionable replacement suggestions
407
+ - On scheduled runs, automatically creates a GitHub Issue with the full broken links report
408
+
409
+ Fixes #27
410
+
411
+ ## 0.5.1
412
+
413
+ ### Patch Changes
414
+
415
+ - e398190: Add comprehensive best practices comparison and improve CI concurrency
416
+ - Add DETAILED-COMPARISON.md with side-by-side analysis of ALL scripts, workflows, and configurations
417
+ - Implement cancel-in-progress for main branch concurrency (hive-mind Issue #1274 fix)
418
+ - Fix max-lines documentation (1500, not 1000)
419
+ - Reference detailed comparison from BEST-PRACTICES.md
420
+
421
+ ## 0.5.0
422
+
423
+ ### Minor Changes
424
+
425
+ - 66211b5: Add fresh merge simulation to CI/CD to prevent stale merge preview issues
426
+ - Add "Simulate fresh merge with base branch" step to lint and test jobs
427
+ - This ensures PR CI validates the actual merge result, not a stale snapshot
428
+ - Prevents CI failures on main branch after merging PRs that sat open for days
429
+ - Add case study documentation for issue #23 with root cause analysis
430
+ - Add ignore patterns for case study data files in ESLint and Prettier
431
+
432
+ See docs/case-studies/issue-23 for detailed analysis of the stale merge preview problem.
433
+
434
+ Fixes #23
435
+
436
+ ## 0.4.0
437
+
438
+ ### Minor Changes
439
+
440
+ - e6c2691: Add multi-language repository support for CI/CD scripts
441
+ - Add `scripts/js-paths.mjs` utility for automatic JavaScript package root detection
442
+ - Support both `./package.json` (single-language) and `./js/package.json` (multi-language repos)
443
+ - Add `--legacy-peer-deps` flag to npm install commands in release scripts to fix ERESOLVE errors
444
+ - Save and restore working directory after `cd` commands to fix `command-stream` library's `process.chdir()` behavior
445
+ - Add case study documentation with root cause analysis in `docs/case-studies/issue-21/`
446
+
447
+ ## 0.3.0
448
+
449
+ ### Minor Changes
450
+
451
+ - 80d9c84: Add CI check to prevent manual version modification in package.json
452
+ - Added `check-version.mjs` script that detects manual version changes in PRs
453
+ - Added `check-changesets.mjs` script to check for pending changesets (converted from inline shell)
454
+ - Added `version-check` job to release.yml workflow
455
+ - Automated release PRs (changeset-release/_ and changeset-manual-release-_) are automatically skipped
456
+
457
+ ## 0.2.2
458
+
459
+ ### Patch Changes
460
+
461
+ - 9a12139: Fix CI/CD check differences between pull request and push events
462
+
463
+ Changes:
464
+ - Add `detect-changes` job with cross-platform `detect-code-changes.mjs` script
465
+ - Make lint job independent of changeset-check (runs based on file changes only)
466
+ - Allow docs-only PRs without changeset requirement
467
+ - Handle changeset-check 'skipped' state in dependent jobs
468
+ - Exclude `.changeset/`, `docs/`, `experiments/`, `examples/` folders and markdown files from code changes detection
469
+
470
+ ## 0.2.1
471
+
472
+ ### Patch Changes
473
+
474
+ - 55aef41: Make Bun the primary runtime choice throughout the template
475
+ - Update all shebangs from `#!/usr/bin/env node` to `#!/usr/bin/env bun` in scripts, experiments, and case studies
476
+ - Update README.md to prioritize Bun in all sections (features, development, runtime support, package managers, scripts reference)
477
+ - Update examples to list Bun first
478
+ - Bun now described as "Primary runtime with highest performance" and "Primary choice" for package management
479
+ - Maintains full compatibility with Node.js and Deno
480
+
481
+ ## 0.2.0
482
+
483
+ ### Minor Changes
484
+
485
+ - d3f7fcd: Improve changeset CI/CD robustness for concurrent PRs
486
+ - Update validate-changeset.mjs to only check changesets ADDED by the current PR (not pre-existing ones)
487
+ - Add merge-changesets.mjs script to combine multiple pending changesets during release
488
+ - Merged changesets use highest version bump type (major > minor > patch) and combine descriptions chronologically
489
+ - Update release workflow to pass SHA environment variables and add merge step
490
+ - Add comprehensive case study documentation for the CI/CD improvement
491
+ - This prevents PR failures when multiple PRs merge before a release cycle completes
492
+
493
+ ## 0.1.4
494
+
495
+ ### Patch Changes
496
+
497
+ - e9703b9: Add ESLint complexity rules with reasonable thresholds
498
+
499
+ ## 0.1.3
500
+
501
+ ### Patch Changes
502
+
503
+ - 0198aaa: Add case study documentation comparing best practices from effect-template
504
+
505
+ This changeset adds comprehensive documentation analyzing best practices from
506
+ ProverCoderAI/effect-template repository, identifying gaps in our current setup,
507
+ and providing prioritized recommendations for improvements.
508
+
509
+ Key findings include missing best practices like code duplication detection (jscpd),
510
+ ESLint complexity rules, VS Code settings, and test coverage thresholds.
511
+
512
+ ## 0.1.2
513
+
514
+ ### Patch Changes
515
+
516
+ - 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.
517
+
518
+ ## 0.1.1
519
+
520
+ ### Patch Changes
521
+
522
+ - 042e877: Fix GitHub release formatting to support Major/Minor/Patch changes
523
+
524
+ The release formatting script now correctly handles all changeset types (Major, Minor, Patch) instead of only Patch changes. This ensures that:
525
+ - Section headers are removed from release notes
526
+ - PR detection works for all release types
527
+ - NPM badges are added correctly
528
+
529
+ ## 0.1.0
530
+
531
+ ### Minor Changes
532
+
533
+ - 65d76dc: Initial template setup with complete AI-driven development pipeline
534
+
535
+ Features:
536
+ - Multi-runtime support for Node.js, Bun, and Deno
537
+ - Universal testing with test-anywhere framework
538
+ - Automated release workflow with changesets
539
+ - GitHub Actions CI/CD pipeline with 9 test combinations
540
+ - Code quality tools: ESLint + Prettier with Husky pre-commit hooks
541
+ - Package manager agnostic design
542
+
543
+ All notable changes to this project will be documented in this file.
544
+
545
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
546
+ 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
- # Temporary Holding Version
1
+ # @link-foundation/universal-translator
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.11.32",
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));