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.

feat(install): prepare native dependencies concurrently and guide all hosts

罗高b031a601e3da
diff --git a/docs/install.md b/docs/install.md
index dc56f664..8e24a319 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -6,24 +6,34 @@ If you are reading this file in the source repository and see `{{...}}`, it is a
## Instructions for the Agent
-1. Check the user's OS/CPU, Node.js and npm, and selected Agent. Node.js 22.18+ with npm and the Agent must already be installed. Supported native targets: {{TARGETS}}. Do not claim support for another target from package-download success.
-2. Use the current host if it is supported; otherwise ask the user to select one. Setup supports `codex`, `claude`, `deepseek` and `workbuddy`. Configure only that host. Preserve existing projects, credentials and unrelated MCP/Skills settings.
+1. Collect OS/CPU, Node.js/npm versions and the current Agent identity together, using the host's supplied context where available. Node.js 22.18+ with npm and the Agent must already be installed. Supported native targets: {{TARGETS}}. Do not claim support for another target from package-download success.
+2. Select the current host explicitly: `codex` (Codex), `claude` (Claude Code), `deepseek` (DeepSeek Harness) or `workbuddy` (WorkBuddy). An explicit user selection takes precedence. Do not infer the current host from which CLIs happen to be installed. Ask only when the current host or required profile cannot be established. Configure only that host; preserve projects, credentials and unrelated MCP/Skills settings.
3. For a test candidate, use a separate host profile, application home, project data and Skills directory. Keep those paths and reuse them for prepare and future reconnects. The [platform installation recipes]({{DETAILS_URL}}) describe the actual supported options. Do not run a test candidate into the user's daily profile by default.
-4. Install the exact package version below, run prepare, then refresh that host to discover the new installation or changed Tools/Skills. Compatible phase-one updates can keep their existing connections; reconnect closed or incompatible transports. Confirm the application version, template environment, eleven public Tools and five Skills. A registration entry alone does not prove the host has loaded them.
+4. Choose exactly one setup command below, applying the test isolation paths first when required. Run prepare only after successful setup, with the same application home, and wait for completion before native operations. 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.
-For a normal Codex installation, the command shape is:
+## 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.
+
+| Current Agent | Setup command | Host-specific selection |
+| --- | --- | --- |
+| Codex | `npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host codex` | Preserve the selected `CODEX_HOME` and Skills root. |
+| Claude Code | `npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host claude` | Preserve the selected `CLAUDE_CONFIG_DIR` and Skills root. |
+| DeepSeek Harness | `npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host deepseek --profile PROFILE` | Replace `PROFILE` with the actual selected profile from the host context; do not guess `web` or `desktop`. The standard macOS Desktop CLI is detected even when `dsh` is absent from PATH; use `--dsh` for another executable location. |
+| WorkBuddy | `npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host workbuddy` | Preserve the selected `WORKBUDDY_CONFIG_DIR` and Skills root. |
+
+Then prepare the same installation:
```sh
-npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host codex
npx --yes --package "{{PACKAGE_SPEC}}" openmotion prepare
```
-For test installations, add the isolated paths/profile from step 3 before executing. For another supported host, use its setup `--host` value and documented profile settings. Setup installs the selected host's MCP and Skills; a second installer or application/manifest download is unnecessary.
+Repeat an explicit `--home` from setup on prepare. Setup installs the selected host's MCP and Skills; a second installer or application/manifest download is unnecessary. Use `openmotion --help`, `setup --help` or `prepare --help` from this exact package for supported options. Inspect installer source or host internals only to investigate a concrete failure; a missing CLI on PATH alone is not a reason to create a wrapper.
## Runtime and environment
-Setup copies the checked application into a managed writable directory and installs its locked production npm dependencies. The application and user projects do not run from the temporary npx cache. FFmpeg, ffprobe and the browser are downloaded and verified by prepare or first native use; this is not an offline package.
+Setup copies the checked application into a managed writable directory and installs its locked production npm dependencies. The application and user projects do not run from the temporary npx cache. Prepare or first native use prepares the platform's independent native archives concurrently: browser/FFmpeg/ffprobe separately on macOS, browser/combined media on Windows. It waits for all components and reports a failure if any component fails; successful checked components remain reusable. This is not an offline package.
There is no persisted switch-environment command in this version. Internal DEV testing uses its separately configured installation; merely setting an environment variable while running setup does not configure a later desktop Agent. Do not silently fall back from one environment to another.
diff --git a/docs/npm-installation.md b/docs/npm-installation.md
index 33400831..df6e65e2 100644
--- a/docs/npm-installation.md
+++ b/docs/npm-installation.md
@@ -82,6 +82,21 @@ There is no automatic fallback from prod to DEV and no `switch-env` CLI. This se
Select `--host codex|claude|deepseek|workbuddy`. `--skills-dir` selects the Codex/Claude/WorkBuddy root; Harness uses its own provider. Executable overrides are `--codex`, `--claude`, `--dsh`; Harness also accepts `--profile`. Isolate host configuration with `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `DSH_HOME` or `WORKBUDDY_CONFIG_DIR`; `--home` controls the application installation, not the host profile.
+Use the same installation flow for every host: collect the platform and Node/npm facts once, select the current Agent, run its setup adapter, prepare the same home, then verify actual host loading. An explicit `--host` takes precedence over host context; do not choose a host merely because its CLI is installed. The CLI retains its Codex default for compatibility, so Agent-driven installs should always pass `--host`. Only ask for the missing host/profile when reliable context is unavailable. `openmotion --help`, `setup --help`, `prepare --help` and `--version` work without installing or modifying configuration.
+
+For a non-Codex test, keep the isolated application/data paths from the examples above and change only the host-specific configuration:
+
+| Selected host | Isolated host configuration | Setup adapter options |
+| --- | --- | --- |
+| Codex | Separate `CODEX_HOME` | `--host codex --skills-dir <isolated-skills-root>` |
+| Claude Code | Separate `CLAUDE_CONFIG_DIR` | `--host claude --skills-dir <isolated-skills-root>` |
+| DeepSeek Harness | Separate `DSH_HOME` and selected profile | `--host deepseek --profile <selected-profile>`; Skills live in this installation's managed bundle |
+| WorkBuddy | Separate `WORKBUDDY_CONFIG_DIR` | `--host workbuddy --skills-dir <isolated-skills-root>` |
+
+Harness callers should pass the actual current profile from their host context, such as `DSH_PROFILE`, rather than assuming `web` or `desktop`. On macOS, setup already detects the standard Desktop CLI at `/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh`; it need not be on PATH. Keep that host-specific lookup in the Harness adapter. Other executable locations use `--dsh`; do not unpack the host or invent a wrapper for ordinary installation.
+
+After prepare, use each host's supported discovery/reload action to load the Tools and Skills. Confirm all eleven public Tools and five Skills, and call `motion_get_project` to verify the expected data directory. Do not impose another host's restart or refresh procedure, or substitute an on-disk registration for host loading evidence.
+
The internal ownership marker remains stable across the npm package rename so earlier local installations can be upgraded in place. An installation can serve multiple hosts using the same home/data. `install.json.hosts` retains each host. Skill documentation links are rewritten for flat layouts; Codex/Harness retain bundle-relative links. Re-run setup for each installed host when upgrading Skills. Unowned same-name MCP/Skills are refused. Unrelated settings/Skills and existing projects are retained. Registration failure restores the prior install state and Skills; checked application caches remain available for retry.
Compatible phase-one updates do not require closing existing MCP connections or stopping the same workspace's backend. Connections negotiate the API protocol and requested Tool, retaining running exports and completed results; see [shared editor recovery](shared-editor.md). The installer does not terminate existing processes. Incompatible protocols or internal legacy ABIs still require updating the connection and idle backend together. Refresh the host to discover new Tools or reload changed Skills; an already-closed transport needs host reconnection.
@@ -98,7 +113,7 @@ Before upgrading, back up projects/configuration, run setup with the new exact t
## Native tools and diagnostics
-The runtime lock pins HTTPS URLs, versions, target OS/CPU and SHA256 for FFmpeg, ffprobe and Chrome for Testing. Downloads require no repository credentials, never attach repository tokens, and do not run brew/winget. Separate component locks, temporary extraction and completion markers support retry/cache reuse. A failed download is not ready. Explicit native path overrides remain supported. See [runtime details](test-packages.md).
+The runtime lock pins HTTPS URLs, versions, target OS/CPU and SHA256 for FFmpeg, ffprobe and Chrome for Testing. Downloads require no repository credentials, never attach repository tokens, and do not run brew/winget. Independent archives are prepared concurrently from the existing platform manifest: three separate components on macOS, browser and combined media on Windows. Preparation settles every component before returning; any failure rejects the operation while completed components remain reusable. Separate component locks, temporary extraction and completion markers retain retry/cache protection. A failed download is not ready. Explicit native path overrides remain supported. See [runtime details](test-packages.md).
A local `--manifest /absolute/release-npm.json` remains available for legacy delivery and controlled fixtures. HTTP, URL credentials, unsafe extraction paths and invalid hashes are rejected. Do not remove a leftover install lock until its owning process is confirmed stopped.
diff --git a/scripts/npm-installer.mjs b/scripts/npm-installer.mjs
index cba4034e..20949941 100644
--- a/scripts/npm-installer.mjs
+++ b/scripts/npm-installer.mjs
@@ -8,13 +8,35 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
import { parseArgs } from 'node:util';
import { canonical, extractArchive, nativeComponents, obtainAsset, readJSON, relativePath, runFile, withLock, writeAtomic, writeJSON } from './runtime-assets.mjs';
import { ensureNativeRuntime } from './npm-runtime.mjs';
-import { hostPlan, skillTargets, obsoleteSkills, checkSkillOwner, copyHostSkills } from './npm-hosts.mjs';
+import { hosts, hostPlan, skillTargets, obsoleteSkills, checkSkillOwner, copyHostSkills } from './npm-hosts.mjs';
// Keep ownership stable so earlier local installations remain upgradable.
export const managedBy = '@openmotion/installer';
const bundledManifest = fileURLToPath(new URL('../payload/release-npm.json', import.meta.url));
const defaultHome = (environment = 'prod') => path.join(process.platform === 'win32' ? process.env.LOCALAPPDATA || os.homedir() : path.join(os.homedir(), '.local/share'), environment === 'dev' ? 'openmotion-dev' : 'openmotion');
const contains = (parent, child) => { const rel = path.relative(parent, child); return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel)); };
+const usage = `Usage:
+ openmotion setup --host <${hosts.join('|')}> [options]
+ openmotion prepare [--home DIR]
+ openmotion --version
+
+Select the current Agent host explicitly; installed CLIs do not identify the current host.
+Setup options:
+ --host HOST Supported hosts: ${hosts.join(', ')} (default: codex)
+ --home DIR Managed application home; reuse for prepare and upgrades
+ --data-dir DIR Project data outside application/cache directories
+ --skills-dir DIR Skills root for Codex, Claude Code or WorkBuddy
+ --codex FILE Codex executable or JavaScript CLI entry
+ --claude FILE Claude Code executable
+ --dsh FILE Harness executable (macOS Desktop CLI is detected automatically)
+ --profile NAME Harness profile (default: web); use the selected host profile
+ --manifest FILE Explicit release manifest for controlled local installations
+
+Run prepare after successful setup and wait before native project operations.
+Refresh the selected host's Tools/Skills; registration alone does not prove loading.
+Use separate host configuration, home, data and Skills paths for test candidates.
+ -h, --help Show this help without installing or changing configuration
+ --version Show this package's version`;
export async function localManifest(filename) {
const file = path.resolve(filename), manifest = await readJSON(file);
@@ -128,9 +150,12 @@ export async function setup(options) {
async function main() {
const { positionals, values } = parseArgs({ allowPositionals: true, options: {
manifest: { type: 'string' }, home: { type: 'string' }, 'data-dir': { type: 'string' }, 'skills-dir': { type: 'string' }, host: { type: 'string' }, codex: { type: 'string' }, claude: { type: 'string' }, dsh: { type: 'string' }, profile: { type: 'string' },
+ help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' },
} });
+ if (values.help) { console.log(usage); return; }
+ if (values.version) { console.log((await readJSON(new URL('../package.json', import.meta.url))).version); return; }
const [command] = positionals;
- assert(positionals.length === 1, 'Usage: openmotion setup --host codex|claude|deepseek|workbuddy [--manifest FILE] [--home DIR] [--data-dir DIR] [--skills-dir DIR] [--codex EXECUTABLE] | prepare --home DIR');
+ assert(positionals.length === 1, usage);
if (command === 'setup') {
console.log(JSON.stringify(await setup({ manifest: values.manifest, home: values.home, dataDirectory: values['data-dir'], skillsDirectory: values['skills-dir'], host: values.host, codex: values.codex, claude: values.claude, dsh: values.dsh, profile: values.profile }), null, 2));
} else if (command === 'prepare') {
@@ -141,4 +166,4 @@ async function main() {
console.log('Pinned FFmpeg, ffprobe and browser are ready.');
} else throw new Error('Supported commands: setup, prepare');
}
-if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) main().catch(error => { console.error(error.message); process.exitCode = 1; });
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) main().catch(error => { console.error(error.message + '\nRun openmotion --help for supported hosts and installation options.'); process.exitCode = 1; });
diff --git a/scripts/npm-runtime.mjs b/scripts/npm-runtime.mjs
index b345076f..69fb832a 100644
--- a/scripts/npm-runtime.mjs
+++ b/scripts/npm-runtime.mjs
@@ -42,9 +42,9 @@ export async function ensureNativeRuntime(root) {
const overrides = Object.fromEntries(Object.entries(paths).filter(([key, value]) => process.env[key] !== value));
for (const key of Object.keys(overrides)) await executable(process.env[key]);
const componentKeys = { browser: ['HYPERFRAMES_BROWSER_PATH'], media: ['HYPERFRAMES_FFMPEG_PATH', 'HYPERFRAMES_FFPROBE_PATH'], ffmpeg: ['HYPERFRAMES_FFMPEG_PATH'], ffprobe: ['HYPERFRAMES_FFPROBE_PATH'] };
- for (const component of components) {
+ const prepared = await Promise.allSettled(components.map(async component => {
const keys = componentKeys[component];
- if (keys.every(key => Object.hasOwn(overrides, key))) continue;
+ if (keys.every(key => Object.hasOwn(overrides, key))) return;
const asset = info[component];
assert(/^[a-f0-9]{64}$/.test(asset.sha256), 'Require a pinned native SHA256');
if (process.platform === 'darwin') assert(Number(os.release().split('.')[0]) >= 25, 'Pinned native downloads require macOS 26 or later; supply compatible media and browser paths on older systems.');
@@ -54,7 +54,7 @@ export async function ensureNativeRuntime(root) {
if ((await readJSON(path.join(destination, 'ready.json')))?.sha256 !== asset.sha256) return false;
try { for (const key of keys) await executable(paths[key]); return true; } catch { return false; }
};
- if (await ready()) continue;
+ if (await ready()) return;
await withLock(destination + '.lock', async () => {
if (await ready()) return;
console.error(`OpenMotion: downloading pinned ${component}; this first use needs network access.`);
@@ -75,6 +75,8 @@ export async function ensureNativeRuntime(root) {
await rename(temporary, destination);
} finally { await rm(temporary, { recursive: true, force: true }); }
});
- }
+ }));
+ const failed = prepared.find(result => result.status === 'rejected');
+ if (failed) throw failed.reason;
for (const [key] of Object.entries(overrides)) await runFile(process.env[key], [key.includes('BROWSER') ? '--version' : '-version']);
}
diff --git a/tests/install-guide.test.ts b/tests/install-guide.test.ts
index 13976f39..f870d05b 100644
--- a/tests/install-guide.test.ts
+++ b/tests/install-guide.test.ts
@@ -47,6 +47,8 @@ test('guide rendering pins the exact npm package, built source and hash while re
assert(text.includes(manifest.commit) && text.includes(record.tgzSHA256));
assert(!text.includes('{{') && !text.includes('see `{{...}}`'));
assert(text.includes('eleven public Tools') && text.includes('five Skills'));
+ 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.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));
diff --git a/tests/npm-installer.test.ts b/tests/npm-installer.test.ts
index c0be0246..e403b2c3 100644
--- a/tests/npm-installer.test.ts
+++ b/tests/npm-installer.test.ts
@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
import { pathToFileURL } from 'node:url';
import { fileURLToPath } from 'node:url';
import { localManifest, setup } from '../scripts/npm-installer.mjs';
+import { hosts } from '../scripts/npm-hosts.mjs';
import { configureNativeEnvironment, ensureNativeRuntime, nativeConfiguration } from '../scripts/npm-runtime.mjs';
import { obtainAsset, relativePath, runFile, sha256, withLock, writeJSON } from '../scripts/runtime-assets.mjs';
@@ -111,6 +112,42 @@ test('installation locks reject simultaneous mutation and release after an error
await withLock(filename, async () => {});
});
+test('native preparation runs independent components together for separate and combined media archives', { skip: process.platform === 'win32', timeout: 20_000 }, async t => {
+ for (const combined of [false, true]) await t.test(combined ? 'combined media' : 'separate media', async t => {
+ clearNativeEnvironment(t);
+ const dir = await fixture(t), root = path.join(dir, 'app'); await mkdir(root);
+ const components = combined ? ['browser', 'media'] : ['browser', 'ffmpeg', 'ffprobe'];
+ const assets: Record<string, any> = {};
+ const downloads = new Map<string, Buffer>(), started: string[] = [];
+ for (const component of components) {
+ const source = path.join(dir, component); await mkdir(source);
+ if (component === 'media') await mkdir(path.join(source, 'bin'));
+ for (const tool of component === 'media' ? ['ffmpeg', 'ffprobe'] : [component]) {
+ await writeFile(path.join(source, component === 'media' ? 'bin' : '', tool), '#!/bin/sh\necho fixture-version\n', { mode: 0o755 });
+ }
+ assets[component] = { ...await archive(dir, source, component), ...(component === 'media' ? { directory: '.' } : { executable: component }) };
+ const bytes = await readFile(new URL(assets[component].url));
+ assets[component].url = `https://example.invalid/${component}.tar.gz`;
+ downloads.set(assets[component].url, bytes);
+ }
+ const gate = Promise.withResolvers<void>();
+ const timeout = setTimeout(() => gate.reject(new Error('Independent downloads did not start together')), 5000);
+ t.after(() => clearTimeout(timeout));
+ t.mock.method(globalThis, 'fetch', async (url: URL) => {
+ started.push(url.href);
+ if (started.length === components.length) gate.resolve();
+ await gate.promise;
+ return new Response(downloads.get(url.href));
+ });
+ await writeJSON(path.join(root, '.npm-install.json'), { schemaVersion: 1, cacheDirectory: path.join(dir, 'cache'), allowLocalAssets: true,
+ runtime: { targets: { fixture: { platform: process.platform, arch: process.arch, ...assets } } } });
+ await ensureNativeRuntime(root);
+ assert.deepEqual(started.sort(), [...downloads.keys()].sort());
+ const native = await nativeConfiguration(root);
+ assert.deepEqual((await readdir(native.cache)).sort(), Object.entries(assets).map(([name, asset]: any) => name + '-' + asset.sha256).sort());
+ });
+});
+
test('separate ffmpeg and ffprobe archives validate independently and recover without replacing a ready tool', { skip: process.platform === 'win32' }, async t => {
clearNativeEnvironment(t);
const dir = await fixture(t), assets: Record<string, any> = {};
@@ -139,6 +176,20 @@ test('separate ffmpeg and ffprobe archives validate independently and recover wi
await writeJSON(manifest, value); await assert.rejects(localManifest(manifest), /SHA256/);
});
+test('CLI help and version cover every host without reading a manifest or changing an installation', async t => {
+ const directory = await fixture(t), cli = fileURLToPath(new URL('../scripts/npm-installer.mjs', import.meta.url));
+ const missing = path.join(directory, 'missing.json'), home = path.join(directory, 'app');
+ for (const command of [['--help'], ['setup', '-h'], ['prepare', '--help']]) {
+ const help = await runFile(process.execPath, [cli, ...command, '--manifest', missing, '--home', home]);
+ for (const host of hosts) assert(help.includes(host), host);
+ for (const option of ['--profile', '--skills-dir', '--codex', '--claude', '--dsh']) assert(help.includes(option), option);
+ }
+ const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+ assert.equal((await runFile(process.execPath, [cli, '--version', '--manifest', missing, '--home', home])).trim(), pkg.version);
+ await assert.rejects(runFile(process.execPath, [cli, 'setup', '--unknown-option']), /openmotion --help/);
+ assert.deepEqual(await readdir(directory), []);
+});
+
test('npm bin symlink executes the CLI instead of silently exiting', { skip: process.platform === 'win32' }, async t => {
const directory = await fixture(t), link = path.join(directory, 'openmotion');
await symlink(fileURLToPath(new URL('../scripts/npm-installer.mjs', import.meta.url)), link);
diff --git a/tests/npm-package.test.ts b/tests/npm-package.test.ts
index 03b9916f..d55dc3b1 100644
--- a/tests/npm-package.test.ts
+++ b/tests/npm-package.test.ts
@@ -56,6 +56,10 @@ test('test npm artifacts contain their application, locked manifest and no bundl
assert.equal(metadata.name, (await json('packages/npm/package.json')).name);
assert.equal(metadata.publishConfig.tag, 'test'); assert.equal(metadata.publishConfig.access, 'public');
assert.equal(metadata.bin.openmotion, 'scripts/npm-installer.mjs');
+ const cli = path.join(installer, 'package', metadata.bin.openmotion);
+ assert.equal((await runFile(process.execPath, [cli, '--version'])).trim(), version);
+ const help = await runFile(process.execPath, [cli, 'setup', '--help']);
+ for (const host of ['codex', 'claude', 'deepseek', 'workbuddy']) assert(help.includes(host), host);
await readFile(path.join(installer, 'package/LICENSE'));
assert.deepEqual((await readdir(path.join(application, 'skills'))).sort(), [...phase1Skills].sort());
assert.equal(await sha256(path.join(application, 'package-lock.json')), release.locks.npm);