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.
TypeScript agent-skillsagentic-aiai-agentsai-videobyokclaude-codecodexdeepseek-harnessdsh-plugingenerative-ailocal-firstmcpmotionmotion-graphicsmultimodalopenmotionreverse-engineeringvideo-editingvideo-generationworkbuddy
docs(installer): guide recovery from npm download failures
罗高7a272012701a
diff --git a/docs/install.md b/docs/install.mdindex 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 a4. 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 commandThe 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.mdindex 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 connectionRun the installed CLI with the same application home and selected host:diff --git a/tests/install-guide.test.ts b/tests/install-guide.test.tsindex 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));