Fix #60: restore root use.{js,cjs,mjs} CDN mirrors broken by 8.14.0 src/ move

[konard]

Summary

Fixes #60. After [email protected] moved the entry files into src/, the historical CDN bootstrap URL https://unpkg.com/use-m/use.js started returning 404. Consumers that eval() the response body without checking the HTTP status evaluated the 404 text as JavaScript and crashed with the cryptic:

SyntaxError: Unexpected identifier 'found'

This PR restores the root-level use.js / use.cjs / use.mjs files while keeping src/ as the single source of truth, so every existing consumer keeps working unchanged after upgrading — and documents how to fix affected projects on any version.

Root cause

• 8.14.0 (PR Resilient CDN loading: shared loadWithFallback engine + per-package fallback + robust use-m/load bootstrap (#58) #59, commit ecee09e) moved use.{js,cjs,mjs} and friends into src/ and updated the package.json exports map.
• unpkg and jsDelivr serve raw published files and ignore the exports map. A bare URL like https://unpkg.com/use-m/use.js only resolves if a real file lives at the package root. After the move, that path 404'd:
  • unpkg body: Not found: /[email protected]/use.js → eval() → SyntaxError: Unexpected identifier 'found'
• The long-standing bootstrap (e.g. @link-assistant/hive-mind's use-m-bootstrap.lib.mjs) does eval(await (await fetch(url)).text()), so the 404 body was eval'd directly.

Reproduced end-to-end in experiments/issue60-root-url-regression.mjs.

CDN behavior, verified against the live services (2026-06-15)

URL	Result
https://unpkg.com/use-m/use.js	404 Not found
https://unpkg.com/[email protected]/use.js	404 Not found
https://cdn.jsdelivr.net/npm/[email protected]/use.js	404 Couldn't find the requested file
https://cdn.jsdelivr.net/npm/use-m/use.js (unversioned)	200, but stale pre-src/ copy ⚠️
https://unpkg.com/use-m/src/use.js	200, valid current JS
https://cdn.jsdelivr.net/npm/use-m/src/use.js	200, valid current JS

⚠️ The reason the maintainer's analysis saw jsDelivr return 200 for the unversioned bare URL: jsDelivr falls back to an older cached version that still had a root use.js, so it silently serves outdated code. The pinned @8.14.0 bare URL correctly 404s. The only reliable cross-CDN workaround is the explicit /src/ path.

The fix

• Restored root mirrors use.js, use.cjs, use.mjs as full copies of src/use.*, generated by scripts/sync-root-entries.mjs (npm run sync:entries). src/ remains canonical; the mirrors carry an AUTO-GENERATED header.
• Why full copies, not require('./src/use.js') shims? (The shim was the maintainer's first suggestion.) The bootstrap fetches and eval()s use.js directly, so a shim runs in the consumer's scope, where it just swaps one cryptic error for another instead of returning a working use. Verified experimentally:
  • In the real ESM consumer (use-m-bootstrap.lib.mjs): ReferenceError: module is not defined
  • In a browser: ReferenceError: require is not defined
  • In CJS with the wrong CWD: Cannot find module './src/use.js'
  • Even if it resolved, src/use.js has no module.exports (it ends in a bare makeUse(...) expression), so a shim yields {} — never a working use.
• package.json: added the three mirrors to files[], bumped 8.14.0 → 8.14.1 (triggers the release workflow), and added the sync:entries script. The exports map still maps ./use.cjs and ./use.mjs to src/ (real modules); use.js stays eval-only and is intentionally not advertised as an importable subpath (matching historical behavior).
• Drift guard: tests/root-entries.test.mjs (14 cases) asserts the mirrors exist, stay byte-for-byte in sync with src/, eval/import to a working use, and ship in the npm tarball — and pins the regression (the 404 body throws SyntaxError; the mirror does not).

Confirmed via npm pack --dry-run that the published tarball now contains both the root mirrors and src/ (15 files).

How to fix projects that use use-m (also in the README)

A new README subsection — Troubleshooting: SyntaxError: Unexpected identifier 'found' — documents three remedies:

1. Recommended — upgrade. Ensure your CDN URL resolves to 8.14.1+ (e.g. pin https://unpkg.com/[email protected]/use.js). No code change needed.
2. One-line workaround (works on every version, incl. 8.14.0). Point the URL at the src/ path on any CDN:
   • https://unpkg.com/use-m/use.js → https://unpkg.com/use-m/src/use.js
   • https://cdn.jsdelivr.net/npm/use-m/use.js → https://cdn.jsdelivr.net/npm/use-m/src/use.js
3. Future-proof. Replace the naive eval(await (await fetch(url)).text()) with a guarded loader that checks response.ok, rejects non-JS bodies, and falls back across mirrors — the packaged use-m/load helper or the self-contained snippet in the README. This prevents any future 404/redirect from being silently eval'd.

Testing

All three runtimes pass, including the new regression test:

Runtime	Result
Node (Jest)	44 suites, 330 tests passed
Bun (bun test)	330 pass, 0 fail
Deno (deno test …)	31 passed (173 steps), 0 failed

CI (node/bun/deno × ubuntu/macos) is green on the latest commit.

Files changed

• experiments/issue60-root-url-regression.mjs — reproduction (incl. shim-failure demo)
• scripts/sync-root-entries.mjs — mirror generator (npm run sync:entries)
• use.js, use.cjs, use.mjs — restored root mirrors (auto-generated)
• package.json — files[], version 8.14.1, sync:entries script
• tests/root-entries.test.mjs — drift + regression guard
• README.md, CHANGELOG.md, CONTRIBUTING.md — docs

Closes #60

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $7.648964
• Calculated by Anthropic: $8.625078
• Difference: $0.976114 (+12.76%)

📊 Context and tokens usage:

Claude Opus 4.8: (2 sub-sessions)

1. 116.0K / 1M (12%) input tokens, 49.7K / 128K (39%) output tokens
2. 93.0K / 1M (9%) input tokens, 35.2K / 128K (28%) output tokens

Total: (20.1K new + 262.2K cache writes + 7.3M cache reads) input tokens, 90.5K output tokens, $7.648964 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.8 (claude-opus-4-8)

📎 Log file uploaded as Gist (3339KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag

[konard]

We need to fix CI/CD, and double check all changes are correct, and requirements from the issue fully addressed.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-06-15T12:30:42.459Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

✅ CI fixed, changes re-verified

CI/CD

The only failing check was Test on deno (ubuntu-latest), and the failure was a transient external-CDN flake — not a regression from this PR:

[mjs module] typescript ... use typescript
error: Failed to import 'typescript' from any CDN mirror.
  - deno   (1/1): Failed to import from 'https://esm.sh/typescript@latest'
  - jspm   (1/1): Failed to import from 'https://jspm.dev/typescript'
  - skypack(1/1): Failed to import from 'https://cdn.skypack.dev/typescript'

Evidence it's a flake, not our code:

• The previous run on the exact same commit passed (run 27535790422, all green).
• deno (macos-latest) passed the same typescript test in the same run; only the ubuntu shard hit the CDN hiccup.
• The typescript test imports a third-party package live from public CDNs and is untouched by this PR.

I re-ran the failed job and all 7 checks are now green.

Re-verification of the fix (requirements from #60)

1. Root cause fixed while keeping src/ — root use.{js,cjs,mjs} are restored as full mirrors of src/ (src/ stays the single source of truth). Confirmed no drift: npm run sync:entries produces no changes.
2. Downstream-fix instructions — README troubleshooting section documents upgrade / /src/ URL workaround / guarded loader.

Local verification on this branch:

• npm test → 44 suites, 330 tests passed.
• tests/root-entries.test.mjs → 14/14 passed (mirrors exist, byte-for-byte in sync with src/, eval/import to a working use, ship in the tarball, and the 404-body regression is pinned).
• experiments/issue60-root-url-regression.mjs reproduces the original SyntaxError: Unexpected identifier 'found' and confirms the restored mirrors eval() to a working use.
• main is merged into the branch; working tree clean.

Ready for review.

[konard]

Working session summary

I've resolved the situation. Here's the summary:

What was wrong

The PR (#61) for issue #60 had one failing check: Test on deno (ubuntu-latest).

Root cause of the CI failure

A transient external-CDN flake in the typescript test — unrelated to the PR's changes. The test imports the typescript package live from public CDNs (esm.sh, jspm, skypack), and all three momentarily failed on the ubuntu deno shard. Proof it was a flake, not a regression:

• The prior run on the identical commit had passed (all green).
• deno (macos-latest) passed the same test in the same run.
• I re-ran the failed job → all 7 checks now green.

Verification of the fix itself (issue #60 requirements)

I re-checked both requirements:

1. Root cause fixed while keeping src/ — root use.{js,cjs,mjs} restored as full mirrors of src/, with src/ remaining canonical. npm run sync:entries produces zero drift.
2. Downstream-fix instructions — documented in README (upgrade / /src/ URL workaround / guarded loader).

Local results on the branch:

• npm test → 44 suites, 330 tests passed
• tests/root-entries.test.mjs → 14/14 passed
• The reproduction experiment confirms the original SyntaxError: Unexpected identifier 'found' and that the restored mirrors eval() to a working use.
• main merged into branch; working tree clean.

Actions taken

• Re-ran the flaky deno job (now passing).
• Marked PR Fix #60: restore root use.{js,cjs,mjs} CDN mirrors broken by 8.14.0 src/ move #61 ready for review.
• Posted a status comment: Fix #60: restore root use.{js,cjs,mjs} CDN mirrors broken by 8.14.0 src/ move #61 (comment)

I deliberately did not modify the flaky typescript test — it's an external-CDN reliability matter outside the scope of issue #60, and touching the core loader's retry behavior for all packages would add unwarranted risk to an otherwise clean, focused fix. If you'd like, I can open a separate change to harden that test (e.g. more retries or skipping on network errors) so the flake stops recurring in CI.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $0.916566
• Calculated by Anthropic: $1.058702
• Difference: $0.142136 (+15.51%)

📊 Context and tokens usage:

• 50.3K / 1M (5%) input tokens, 9.1K / 128K (7%) output tokens

Total: (3.3K new + 37.9K cache writes + 873.6K cache reads) input tokens, 9.1K output tokens, $0.916566 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.8 (claude-opus-4-8)

📎 Log file uploaded as Gist (755KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🔄 Auto-restart 1/5

Detected uncommitted changes from previous run. Starting new session to review and commit or discard them.

Uncommitted files:

M package-lock.json

---

Auto-restart will stop after changes are committed or discarded, or after 4 more iterations. Please wait until working session will end and give your feedback.

[konard]

Working session summary

Working tree is clean, the lockfile is committed, and main is already merged into the branch.

The uncommitted change has been resolved. Here's the summary:

What the uncommitted change was

package-lock.json still showed 8.14.0 while package.json had already been bumped to 8.14.1 (committed in 850d4c6 as the release trigger for the #60 fix). The lockfile simply needed to be synced to match.

Action taken

Committed the lockfile sync and pushed:

• Commit 1c2a45d — "Sync package-lock.json version to 8.14.1 (After latest release multiple projects which used use-m failed #60)"
• Pushed to issue-60-4e765a3f3c78

Verification

• git status → clean working tree, no uncommitted changes
• main is confirmed merged into the branch

This was a legitimate, focused change (lockfile version alignment for the release), not stray work — so committing rather than reverting was correct. The PR (#61) state is otherwise unchanged and remains the fix for issue #60.

---

This summary was automatically extracted from the AI working session output.

[konard]

🔄 Auto-restart 1/5 Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $0.225594
• Calculated by Anthropic: $1.352347
• Difference: $1.126753 (+499.46%)

📊 Context and tokens usage:

• 30.6K / 1M (3%) input tokens, 1.5K / 128K (1%) output tokens

Total: (2.9K new + 18.1K cache writes + 120.4K cache reads) input tokens, 1.5K output tokens, $0.225594 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.8 (claude-opus-4-8)

📎 Log file uploaded as Gist (1109KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag