What's wrong
Since PR #526, `urlcode init --with` always resolves bundles over the network from GitHub Releases, with no offline fallback and no guaranteed timing relationship to core's own release. Two related gaps:
1. No offline / air-gapped / local-bundle story
`packages/core/src/extension-bundles.ts` only exposes `githubBundleTransport` as the production `BundleTransport`. The only alternative is the `bundleTransport` option on `initProjectWith` (`init-with.ts:30`), documented as "Test-only transport injection" -- not a supported user-facing escape hatch. There's no `--bundle-release `, no vendoring support, and `installBundle` (`extension-bundles.ts:59`) always calls `transport.release()` over the network even when a matching bundle may already be cached locally under `.urlcode/extension-bundles//`. Runtime bundle loading (`loadExtensionBundle`, used by `serve`) is network-free -- only `init --with` and `extension-bundles install` require network. A user working air-gapped, or just wanting reproducible installs without hitting GitHub each time, has no supported path.
2. Version-drift window with an unhelpful, unactionable error
`init-with.ts` auto-resolves `extension-bundles@v` with no fallback (this is the hard rule from #526 -- by design, not itself the bug). The publish workflow (`.github/workflows/extension-bundles.yml`) only triggers on a manually pushed `extension-bundles@v*` tag or `workflow_dispatch` -- it is NOT triggered by `release-core-dispatch.yml`/`candidate.yml`, so there's no guarantee the matching bundle release exists immediately when a new core version ships. (We confirmed 0.5.9's core and bundle releases both succeeded, ~9 minutes apart -- so this is a real but currently-manual-process-dependent window, not hypothetical.)
When the matching release doesn't exist yet, `createGithubTransport`'s `release()` just throws `Could not fetch extension bundle release extension-bundles@v` -- generic, doesn't explain the timing gap, doesn't mention `--bundle-release` as an escape hatch to pin an older compatible release, and is indistinguishable from an auth/network failure.
Suggested fix
- Improve the error message when the auto-resolved release 404s: mention `--bundle-release ` as an explicit pin, and suggest checking whether the bundle release for this core version has published yet.
- Consider whether `extension-bundles.yml` should be triggered automatically as part of the core release pipeline, closing the window entirely, vs. this being an accepted manual-coordination cost.
- Decide whether a local-file/cache-only `BundleTransport` is worth promoting from test-only to a real, documented option (e.g. for CI/offline use), or whether that's out of scope for the free/self-hosted runtime.
What's wrong
Since PR #526, `urlcode init --with` always resolves bundles over the network from GitHub Releases, with no offline fallback and no guaranteed timing relationship to core's own release. Two related gaps:
1. No offline / air-gapped / local-bundle story
`packages/core/src/extension-bundles.ts` only exposes `githubBundleTransport` as the production `BundleTransport`. The only alternative is the `bundleTransport` option on `initProjectWith` (`init-with.ts:30`), documented as "Test-only transport injection" -- not a supported user-facing escape hatch. There's no `--bundle-release `, no vendoring support, and `installBundle` (`extension-bundles.ts:59`) always calls `transport.release()` over the network even when a matching bundle may already be cached locally under `.urlcode/extension-bundles//`. Runtime bundle loading (`loadExtensionBundle`, used by `serve`) is network-free -- only `init --with` and `extension-bundles install` require network. A user working air-gapped, or just wanting reproducible installs without hitting GitHub each time, has no supported path.
2. Version-drift window with an unhelpful, unactionable error
`init-with.ts` auto-resolves `extension-bundles@v` with no fallback (this is the hard rule from #526 -- by design, not itself the bug). The publish workflow (`.github/workflows/extension-bundles.yml`) only triggers on a manually pushed `extension-bundles@v*` tag or `workflow_dispatch` -- it is NOT triggered by `release-core-dispatch.yml`/`candidate.yml`, so there's no guarantee the matching bundle release exists immediately when a new core version ships. (We confirmed 0.5.9's core and bundle releases both succeeded, ~9 minutes apart -- so this is a real but currently-manual-process-dependent window, not hypothetical.)
When the matching release doesn't exist yet, `createGithubTransport`'s `release()` just throws `Could not fetch extension bundle release extension-bundles@v` -- generic, doesn't explain the timing gap, doesn't mention `--bundle-release` as an escape hatch to pin an older compatible release, and is indistinguishable from an auth/network failure.
Suggested fix