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): guide recovery from npm download failures

罗高7a272012701a
diff --git a/docs/install.md b/docs/install.md
index 56543e97..c58ec283 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -12,6 +12,8 @@ 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.
+
## Choose the selected host's setup command
The commands below show normal installations. For test candidates, apply the separate configuration/profile, home, data and Skills paths from the [platform recipes]({{DETAILS_URL}}) first. Run only the selected row.
diff --git a/docs/npm-installation.md b/docs/npm-installation.md
index eebf1721..5ef89035 100644
--- a/docs/npm-installation.md
+++ b/docs/npm-installation.md
@@ -119,6 +119,18 @@ Before upgrading, back up projects/configuration, run setup with the new exact t
## Native tools and diagnostics
+### npm download failures
+
+Recover the failed stage rather than repeatedly changing registries or reporting an older working installation as the requested upgrade:
+
+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.
+
+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.
+
+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).
+
### Missing MCP tools or a failed connection
Run the installed CLI with the same application home and selected host:
diff --git a/tests/install-guide.test.ts b/tests/install-guide.test.ts
index 316ea039..435b24b5 100644
--- a/tests/install-guide.test.ts
+++ b/tests/install-guide.test.ts
@@ -58,6 +58,8 @@ test('guide rendering pins the exact npm package, built source and hash while re
'A generated test guide must not claim test versions skip DEV templates');
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.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));