Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

docs(installer): prefer bounded automatic npm registry fallback

罗高0d52d037f16d
diff --git a/docs/install.md b/docs/install.md
index c58ec283..bb7b8b5f 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -12,7 +12,7 @@ If you are reading this file in the source repository and see `{{...}}`, it is a
4. Choose exactly one setup command below, applying the test isolation paths first when required. Setup starts checked video-component downloads in the background. Do not wait for prepare to connect MCP, create/edit projects or open ordinary preview. Studio shows preparation status and retry; media import, automated capture and export require their respective components. Follow the selected host's discovery/reload mechanism. Compatible phase-one updates can keep existing connections; reconnect closed or incompatible transports. Confirm the application version, template environment, eleven public Tools and five Skills through that host, including an actual `motion_get_project` call. Registration alone does not prove loading.
5. Report the result and any failed step. Introduce the available capabilities and wait for the user's next request. Installation does not authorize generating a video or calling a paid model.
-If npm downloads fail with `ENOTFOUND`, `EAI_AGAIN` or a timeout, follow [npm download recovery]({{DETAILS_URL}}#npm-download-failures): check the actual Node/npm execution environment and permitted network access before changing registries; if the Agent cannot proceed, provide the complete setup command and selected environment/paths for the user to run in their terminal. Preserve the package identity and host isolation; do not change global npm settings or bypass a network denial. A local tgz still needs npm access for setup's production dependencies.
+For npm network failures, automatically try `https://registry.npmjs.org` then `https://registry.npmmirror.com`, at most once per registry, counting the initial failed attempt. Respect an explicitly selected registry and host policy. Set `npm_config_registry` and `npm_config_fetch_retries=0` only for that attempt, including setup's npm child process. Keep the exact version; verify any mirrored tgz against the matching immutable guide's SHA256 before executing it. If both fail, follow [npm download recovery]({{DETAILS_URL}}#npm-download-failures) for network checks and a terminal handoff. Permission or checksum failures stop immediately. A local tgz still needs npm access for setup's production dependencies.
## Choose the selected host's setup command
diff --git a/docs/npm-installation.md b/docs/npm-installation.md
index 5ef89035..717fc1b2 100644
--- a/docs/npm-installation.md
+++ b/docs/npm-installation.md
@@ -121,15 +121,16 @@ Before upgrading, back up projects/configuration, run setup with the new exact t
### npm download failures
-Recover the failed stage rather than repeatedly changing registries or reporting an older working installation as the requested upgrade:
+Recover npm network failures (`ENOTFOUND`, `EAI_AGAIN`, connection errors or timeouts) automatically before asking the user to troubleshoot:
-1. Identify whether the failure happened while npx fetched `@openmotion/app`, during setup's production `npm ci`, or while preparing native video components. Record the failed hostname, error code, exact package version when known and redacted npm log. `ENOTFOUND`/`EAI_AGAIN` indicate name-resolution failures; a timeout can have several network causes. Neither proves that the requested package/version is missing. Curl or browser access does not establish that the actual Node/npm process has the same access.
-2. Check network access with the same Node/npm and execution environment used for installation. Use `npm ping --registry=https://registry.npmjs.org` to test the official registry, or the user's selected registry when applicable. A successful ping does not verify every package or tarball endpoint. If the host restricts command networking, use its supported approval flow where policy permits; do not disable the sandbox or bypass a denial. Use the user's approved proxy or registry only for this installation, ensuring the settings also reach setup's npm child process; do not change global npm configuration or expose proxy credentials.
-3. If the Agent cannot obtain permitted access, explain the blocker and offer a user-controlled terminal handoff where policy permits. Provide a copyable command for the selected shell with the same package identity, Node/npm, working directory, host/profile, host configuration environment, application home, data and Skills paths. Do not guess the host or replace an exact version with another version/channel. After the user completes setup, refresh/reconnect the actual host and verify its version and `motion_get_project` result before resuming. Keep native preparation readiness separate from host loading.
+1. **Try official, then mirror.** Try `https://registry.npmjs.org` then `https://registry.npmmirror.com`, at most once per registry, counting the initial failed attempt and skipping registries already tried. An explicitly selected registry goes first; respect any user or host restriction on alternatives. Stop on authentication, permission or checksum failures rather than switching sources.
+2. **Keep settings temporary.** Set `npm_config_registry` and `npm_config_fetch_retries=0` for the attempt's process tree, covering both npx and setup's production `npm ci`. Do not change global npm configuration, project lockfiles or TLS verification. This fallback does not apply to separate browser/FFmpeg download hosts.
+3. **Keep the same artifact.** Pin the exact requested/resolved version before switching. For channel tags, use the matching immutable guide and checksum, not the mirror's potentially older tag. If the tag never resolved, use the version stated in the trusted guide. Download a mirrored tgz with lifecycle scripts disabled, verify its SHA256 against that guide before executing it, then use the local-tgz setup command with the same host/profile and isolated paths. A missing mirrored version is not permission to downgrade; a checksum mismatch stops recovery.
+4. **Both failed: diagnose, then hand off.** Compare `npm ping` in the actual installation environment and the user's terminal, using the same npm and registry; curl success alone is insufficient. Use the host's supported network-approval flow where permitted, without bypassing a denial. If Agent access remains unavailable, provide the complete setup command and selected environment/paths for the user's terminal: preserve Node/npm, working directory, host/profile, host configuration, application home, data and Skills paths. After setup, reconnect the host and verify its version and `motion_get_project` result.
-If npm also fails in the user's terminal, resolve the DNS/proxy/network problem first. An official same-version tgz with its published checksum can replace the outer package download when available, using the existing local-tgz commands above, but setup still runs `npm ci` and native preparation still downloads separate assets. This is not an offline fallback. If neither a permitted network path nor a verified complete offline distribution is available, report installation as incomplete and retain the prior installation and user data.
+If the terminal also fails, resolve DNS/proxy/network access first and report installation as incomplete; preserve the previous installation and user data. A verified local tgz only replaces the outer download: production npm dependencies and native components still need network access. Native readiness and host loading remain separate results.
-References: [npm ping](https://docs.npmjs.com/cli/v11/commands/npm-ping/) and [npm proxy configuration](https://docs.npmjs.com/cli/v11/using-npm/config/#https-proxy).
+References: [npmmirror](https://npmmirror.com/), [temporary npm configuration](https://docs.npmjs.com/cli/v11/using-npm/config/#environment-variables) and [npm ping](https://docs.npmjs.com/cli/v11/commands/npm-ping/).
### Missing MCP tools or a failed connection
diff --git a/tests/install-guide.test.ts b/tests/install-guide.test.ts
index 435b24b5..828fa511 100644
--- a/tests/install-guide.test.ts
+++ b/tests/install-guide.test.ts
@@ -59,7 +59,11 @@ test('guide rendering pins the exact npm package, built source and hash while re
for (const host of ['codex', 'claude', 'deepseek', 'workbuddy']) assert(text.includes(`openmotion setup --host ${host}`), host);
assert(text.includes('--profile PROFILE') && text.includes('Do not infer the current host'));
assert(text.includes(`/blob/${manifest.commit}/docs/npm-installation.md#npm-download-failures`), 'Network recovery must link to this package source');
- assert(text.includes('complete setup command and selected environment/paths') && text.includes('A local tgz still needs npm access'), 'Generated guides retain the terminal handoff and online dependency boundary');
+ assert(text.includes('automatically try `https://registry.npmjs.org` then `https://registry.npmmirror.com`'), 'Network recovery must name the ordered automatic fallback');
+ assert(text.includes('at most once per registry, counting the initial failed attempt'), 'Recovery must not retry the same registry indefinitely');
+ assert(text.includes('`npm_config_registry` and `npm_config_fetch_retries=0` only for that attempt, including setup\'s npm child process'), 'Temporary registry settings must reach nested dependency installation');
+ assert(text.includes('verify any mirrored tgz against the matching immutable guide\'s SHA256 before executing it'), 'Mirror recovery must preserve an independently recorded package identity');
+ assert(text.includes('Permission or checksum failures stop immediately') && text.includes('terminal handoff') && text.includes('A local tgz still needs npm access'), 'Retain fail-closed recovery, terminal handoff and the online dependency boundary');
assert.equal(record.channel, 'test'); assert.equal(record.candidate, false);
assert.equal(validateGuideSpec('openmotion', '0.6.4'), 'stable');
for (const name of ['https://evil.invalid/a', 'x;echo bad', '--script', '@bad/no/extra']) assert.throws(() => validateGuideSpec(name, pkg.version));