Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/install-attribution.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Installation attribution

Website URL `?utm_source=producthunt` → copied guide URL with the same query → Worker adds `--utm-source=producthunt` to setup commands → installer saves the source → subsequent events carry `od_utm_source`.

## Compatibility

- No source: the original guide and setup command work unchanged; a new identity has an unknown source.
- Untagged upgrade: keep the saved source and installation ID.
- Explicit new source: update the source while retaining the installation ID.
- The release policy applies: test/prerelease builds do not collect installation attribution or send events. Stable builds honor saved telemetry preferences and environment opt-outs. Reporting failure never fails installation.
- Website current-visit attribution is separate from the existing first-touch cookie. Existing page/tab prompts do not change when another tab arrives from another campaign.

## Deployment order

1. Merge and publish the installer supporting `--utm-source`. Guide generation reads the packaged installer and includes `<!-- openmotion-utm-source-supported -->` only when that exact installer accepts the option, so a guide sealed for an older integrated source never offers it.
2. Deploy `wrangler deploy --config workers/install-guide/wrangler.toml` in the Powerformer account. The binding reads the existing `open-design-releases` bucket; it does not upload or modify release objects.
3. Verify the test entry `open-design.powerformer.net/motion/install.md` against both attributed and direct requests. The Worker maps this host to `open-motion/dev/install.md`.
4. After validation, enable `open-design.ai/motion/install.md` separately; it maps to `open-motion/install.md`. The checked-in route activates only the test host. Other website and R2 paths remain unchanged. Removing the added route rolls back the new entry; existing R2 links remain available.

Both entries may serve older guides without injecting a parameter; injection starts only after a supporting installer and marked guide are published. Website feature previews, and the template prompts they copy, use the test installation entry, while their Pages deployment stays on the feature branch. Copied template prompts keep the existing R2 guide for prod until step 4 activates and verifies that entry. R2 upload/readback origins are not installation entry URLs.

An older guide without the marker is served unchanged, even when a source query is supplied. Transformed responses use `Cache-Control: no-store` to prevent channel mixing. Unrecognized paths return 404; GET and HEAD are supported.

## Measurement

Filter Motion events by `product=openmotion`, environment, date and `od_utm_source`. Count successful installation devices by distinct `installation_id`; count project-creating devices and projects using successful `project_create_result` events. Reinstalls are events, not additional devices. Website copy success is a separate measurement and does not prove installation. There is no cross-device or website-to-client person matching.
2 changes: 2 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- openmotion-utm-source-supported -->
Comment thread
luogao marked this conversation as resolved.
Resolved

## 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.
Expand Down
2 changes: 2 additions & 0 deletions docs/product/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,8 @@ The following product measures still require agreed observation windows and vali

开始采集前需记录事件定义、观察窗口、样本来源和隐私边界。人物、商业和指标实验的证据写回对应文档,不能用开源仓库热度或模板原帖播放量替代。

Installation attribution is optional: `setup --utm-source <channel>` updates the existing installation identity's source after successful host registration. Untagged upgrades retain it; disabled telemetry creates no identity or installation event. Installation and subsequent domain events carry `od_utm_source` without modifying person profiles. The install-guide Worker reads the existing R2 guide and adds the flag only when the guide declares installer support. Unattributed requests and older guides keep their original commands. Deployment and installer publication remain separate; see [installation attribution](../install-attribution.md).

## Application npm distribution

The `@openmotion/app` npm tgz contains installer scripts, the prebuilt application archive and its pinned default manifest. Setup needs only that tgz, stages the checked application into a managed writable directory, installs production npm dependencies from its lock and registers the selected host's eleven MCP Tools and five Skills. The application server and projects never run in the npx cache. Node/Agent remain user-provided. After successful setup, a detached worker prepares pinned FFmpeg, ffprobe and browser assets concurrently. MCP and the local editor backend start without waiting for native downloads. Installers and running apps share platform/hash cache locks and atomic component status; Studio polls readiness and displays preparation progress and failure retry inside the Export panel. The header Export action opens that panel while dependencies are unavailable; readiness updates without reloading. Media import checks the media components before applying work; automated capture and export require the full local runtime because captured compositions may contain media. Selected Studio imports are retained in memory for explicit retry in the same project; preparation does not create or replay exports. Explicit prepare remains a blocking wait/retry, completed assets are reused across app versions sharing the cache, and interrupted transfers restart only the incomplete asset. Existing plugin and complete platform ZIP channels remain available.
Expand Down
2 changes: 1 addition & 1 deletion scripts/distribution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -436,7 +436,7 @@ export const distributionDocuments = [
'tracking/README.md', 'tracking/INTEGRATION.md', 'tracking/posthog-geoip.hog',
'docs/agent-adapters.md', 'docs/browser-runtime.md', 'docs/design-system.md', 'docs/editor-fork.md',
'docs/hyperframes.md', 'docs/mcp-phase1-tools.md', 'docs/model-gateway.md', 'docs/motion-director.md',
'docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/install.md', 'docs/release-guide.md', 'docs/release-workflows.md', 'docs/templates/release-record.md', 'docs/project-workspace.md',
'docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/install-attribution.md', 'docs/install.md', 'docs/release-guide.md', 'docs/release-workflows.md', 'docs/templates/release-record.md', 'docs/project-workspace.md',
'docs/repository-migration.md', 'docs/session-architecture.md', 'docs/shared-editor.md',
'docs/README.zh-CN.md', 'docs/README.ja.md',
'docs/usage.md', 'docs/motion-md.md', 'docs/motion-md.zh-CN.md',
Expand Down
18 changes: 17 additions & 1 deletion scripts/install-guide.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@ import { fileURLToPath } from 'node:url';
import { runFile, sha256, writeAtomic, writeJSON } from './runtime-assets.mjs';
import { checkReleaseVersion, releaseTemplateEnvironment } from './release-version.mjs';

const attributionMarker = '<!-- openmotion-utm-source-supported -->';

// The sealed archive may come from an older integrated source than this control checkout, so
// declare support only for the installer that the guide actually pins.
export function supportsInstallAttribution(installer) {
return /--utm-source\b/.test(installer) && /['"]utm-source['"]\s*:/.test(installer);
}

async function readPackagedInstaller(tgz) {
try { return await runFile('tar', ['-xOf', path.resolve(tgz), 'package/scripts/npm-installer.mjs']); }
catch { return ''; }
}

export function validateGuideSpec(name, version) {
assert.match(name || '', /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/, 'Require an npm package name');
assert(name.length <= 214, 'npm package name is too long');
Expand All @@ -31,16 +44,19 @@ export async function generateInstallGuide(tgz, output, candidate = false) {
const pkg = await readEntry('package/package.json'), manifest = await readEntry('package/payload/release-npm.json');
const channel = validateGuideIdentity(pkg, manifest);
const digest = await sha256(tgz), packageSpec = `${pkg.name}@${pkg.version}`;
const attribution = supportsInstallAttribution(await readPackagedInstaller(tgz));
const values = { VERSION: pkg.version, PACKAGE_SPEC: packageSpec, CHANNEL: channel, COMMIT: manifest.commit,
TEMPLATE_ENVIRONMENT: manifest.templateEnvironment, TGZ_SHA256: digest,
TARGETS: Object.values(manifest.runtime.targets).map(t => `${t.platform}/${t.arch} (${t.minimumOS}+)`).join(', '),
DETAILS_URL: `https://github.com/nexu-io/html-anything/blob/${manifest.commit}/docs/npm-installation.md` };
const template = await readFile(new URL('../docs/install.md', import.meta.url), 'utf8');
// The repository warning is unnecessary after all release placeholders are resolved.
const text = (candidate ? '> Build preview only: this candidate is not an approved registry installation entry.\n\n' : '') + template.replace(/^If you are reading this file.*\n\n/m, '').replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => {
let text = (candidate ? '> Build preview only: this candidate is not an approved registry installation entry.\n\n' : '') + template.replace(/^If you are reading this file.*\n\n/m, '').replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => {
assert(Object.hasOwn(values, key), 'Unknown installation placeholder: ' + key); return values[key];
});
assert(!text.includes('{{'), 'Installation guide has unresolved placeholders');
// An older packaged installer rejects --utm-source, so it must not be offered one.
if (!attribution) text = text.replace(`${attributionMarker}\n\n`, '');
await mkdir(output, { recursive: true });
await writeAtomic(path.join(output, 'install.md'), text);
const record = { schemaVersion: 1, candidate, packageName: pkg.name, version: pkg.version, packageSpec, channel,
Expand Down
10 changes: 8 additions & 2 deletions scripts/npm-installer.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ const usage = `Usage:
Select the current Agent host explicitly; installed CLIs do not identify the current host.
Setup options:
--host HOST Supported hosts: ${hosts.join(', ')} (default: codex)
--utm-source NAME Optional installation source; omitted upgrades retain the existing source
--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
Expand Down Expand Up @@ -66,6 +67,7 @@ export async function localManifest(filename) {
}

export async function setup(options) {
assert(options.utmSource === undefined || /^[A-Za-z0-9_.-]{1,64}$/.test(options.utmSource), 'Invalid --utm-source');
const manifest = await localManifest(options.manifest || bundledManifest);
if (!options.manifest) assert.equal(manifest.version, (await readJSON(new URL('../package.json', import.meta.url))).version, 'Bundled application must match the npm package version');
const templateEnvironment = manifest.templateEnvironment ?? 'prod';
Expand Down Expand Up @@ -137,6 +139,10 @@ export async function setup(options) {
...(plan.host === 'codex' ? { skillsDirectory: targets[0] } : {}) };
await writeJSON(stateFile, state); wroteState = true;
await plan.register();
try {
const { recordInstallation } = await import(pathToFileURL(path.join(appRoot, 'shared/install-attribution.ts')).href);
await recordInstallation(dataDirectory, plan.host, options.utmSource);
} catch (error) { console.error('OpenMotion: installation attribution unavailable: ' + error.message); }
for (const item of directories) await rm(item.backup, { recursive: true, force: true }).catch(error => console.error('Old instruction backup retained: ' + error.message));
await startNativePreparation(appRoot).catch(error => console.error('OpenMotion: background preparation could not start; retry in Studio or run prepare. ' + error.message));
return { ...state, host: plan.host, hostInstallation: plan.metadata, nativeDependencies: 'background-preparation; status and retry available in Studio' };
Expand Down Expand Up @@ -183,14 +189,14 @@ export async function diagnose(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' },
'utm-source': { 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);
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));
console.log(JSON.stringify(await setup({ utmSource: values['utm-source'], 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') {
const environment = (await readJSON(bundledManifest))?.templateEnvironment;
const state = await readJSON(path.join(values.home || defaultHome(environment), 'install.json'));
Expand Down
11 changes: 11 additions & 0 deletions shared/install-attribution.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import path from 'node:path';
import { saveInstallationSource } from '../tracking/node.ts';
import { createAppTracking, closeTracking, trackingLocked, trackingPreference } from './tracking.ts';

export async function recordInstallation(directory: string, host: 'codex' | 'claude' | 'deepseek' | 'workbuddy', source?: string) {
if (trackingLocked() || !trackingPreference(directory)) return;
await saveInstallationSource(path.join(directory, 'tracking'), source);
const tracking = await createAppTracking(directory, 'installer');
tracking.track('installation_result', { outcome: 'success', host_product: host });

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Assert that the installation_result event actually reaches the sender

recordInstallation discards the return value of tracking.track(...), so a registry mistake — a renamed required field, a host value missing from the host_product enum, a wrong entrypoint — silently yields 'invalid' and zero reports while every test stays green: the installer fixture replaces shared/tracking.ts with a stub (tests/npm-installer.test.ts:41), and the new tests/tracking.test.ts case only exercises saveInstallationSource. Because docs/install-attribution.md defines the installation and project metrics from these events, a wiring regression would look identical to "no installations".

Add one test that drives recordInstallation against the real createNodeTracking/createPosthogSender with a capture fetch (the pattern already used in tests/tracking.test.ts) and asserts the emitted installation_result carries outcome, host_product, installation_id and the saved od_utm_source, or at minimum assert track() returns 'queued'.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

await closeTracking(tracking);
}
7 changes: 6 additions & 1 deletion shared/integration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { catalogLocale } from './template-locale.ts';
import { workflowEntryGuide } from './workflow-entry.js';

export const integrationHosts = ['codex', 'claude', 'deepseek', 'chatgpt', 'mcp'] as const;
const TEST_INSTALL_HOST = 'open-design.powerformer.net';
export type IntegrationHost = typeof integrationHosts[number];
export const hostNames: Record<IntegrationHost, string> = { codex: 'Codex', claude: 'Claude Code', deepseek: 'DeepSeek Harness', chatgpt: 'ChatGPT', mcp: 'MCP / CLI' };
export const hostDescriptions: Record<IntegrationHost, string> = {
Expand Down Expand Up @@ -75,7 +76,11 @@ export function setupPrompt(info: IntegrationInfo, host: IntegrationHost, locale
}
export function templatePrompt(info: IntegrationInfo, _host: IntegrationHost, template: { id: string; title: string }, locale = 'zh-CN') {
const environment = info.templateEnvironment ?? info.transport.env?.MOTION_TEMPLATE_ENV ?? 'prod';
const installUrl = `https://releases.open-design.ai/open-motion/${environment === 'dev' ? 'dev/' : ''}install.md`;
// The production website entry stays disabled until it is activated and verified, so prod keeps
// the existing R2 guide; only the enabled test entry moves to its environment host.
const installUrl = environment === 'dev'
? `https://${TEST_INSTALL_HOST}/motion/install.md`
: 'https://releases.open-design.ai/open-motion/install.md';
const message = templatePrompts[catalogLocale(Object.keys(templatePrompts), locale, 'en')];
const values = { installUrl, name: template.title, id: template.id };
return message.replace(/\{(installUrl|name|id)\}/g, (_, key: keyof typeof values) => values[key]);
Expand Down
4 changes: 4 additions & 0 deletions shared/tracking.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ export async function createAppTracking(directory: string, entrypoint: Entry): P
if (!config.host || !config.token) return disabled();
const tracking = createNodeTracking({ registry: omEvents, entrypoint, enabled: true,
identity: await loadIdentity(path.join(directory, 'tracking')), appVersion: VERSION,
source: () => {
try { return JSON.parse(readFileSync(path.join(directory, 'tracking/identity.json'), 'utf8')).utm_source; }
catch { return null; }
},
host: config.host, token: config.token, geoip: config.geoip,
isEnabled: () => !trackingLocked() && trackingPreference(directory),
env: env as 'development' | 'test' | 'production', testRunId: process.env.OPENMOTION_TRACKING_TEST_RUN_ID });
Expand Down
2 changes: 1 addition & 1 deletion studio/src/motion/HomeTemplates.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ it('only editable templates open a new engineering project; references copy thei
await act(async () => button('一键复制').click());
expect(clipboard).toHaveBeenCalledOnce();
expect(clipboard.mock.calls[0][0]).toContain('指定模板:Reference(hf-moment-M953)');
expect(clipboard.mock.calls[0][0]).toContain('https://releases.open-design.ai/open-motion/dev/install.md');
expect(clipboard.mock.calls[0][0]).toContain('https://open-design.powerformer.net/motion/install.md');

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Keep the internal test host out of tracked test literals

.github/scripts/motion-scan.mjs flags any tracked file containing a URL whose host is powerformer.net as rule internal-link; only prism-templates.ts gets a rewrite exemption. I ran its privacyFindings over the full git ls-files tree at 6509ce2: exactly two files report internal-link — this line and studio/src/motion/TemplateLibraryDialog.test.tsx:52 — both added by this commit, while the base commit scanned clean. That makes the standalone CI job fail at "Scan tracked source and test release controls without publication credentials", and it would reject the candidate source scan too, even though every behavioral test here passes.

Fix by never spelling the scheme plus domain in test code: export the dev guide URL from shared/integration.ts (the bare open-design.powerformer.net constant there already passes the scan) and assert with expect(prompt).toContain(devInstallGuideUrl), or keep the regex form that commit 1277b6a used in tests/catalog.test.ts.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

expect(clipboard.mock.calls[0][0]).not.toContain('localhost');
expect(state.open).toHaveBeenCalledTimes(1);
expect(container.textContent).toContain('已复制');
Expand Down
2 changes: 1 addition & 1 deletion studio/src/motion/TemplateLibraryDialog.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ it('copies the requested remote DEV prompt and preserves editable opening', asyn
expect(host.querySelector('dialog[aria-label=复刻模板] textarea')).not.toBeNull();
expect(host.querySelector('dialog[aria-label=模板预览] textarea')).toBeNull();
await act(async () => host.querySelector<HTMLButtonElement>('button[aria-label=复制]')!.click());
expect(navigator.clipboard.writeText).toHaveBeenCalledWith('使用说明:请使用 OpenMotion 插件。如未安装,请按 https://releases.open-design.ai/open-motion/dev/install.md 安装并接入后继续。\n指定模板:First(one)\n创作要求:基于模板,结合我的要求和附件创作,默认保留主要动效与风格,并交付 HTML 和 MP4。\n我的要求:\n');
expect(navigator.clipboard.writeText).toHaveBeenCalledWith('使用说明:请使用 OpenMotion 插件。如未安装,请按 https://open-design.powerformer.net/motion/install.md 安装并接入后继续。\n指定模板:First(one)\n创作要求:基于模板,结合我的要求和附件创作,默认保留主要动效与风格,并交付 HTML 和 MP4。\n我的要求:\n');
await act(async () => button('打开并编辑 ↗').click());
expect(onOpen).toHaveBeenCalledWith('one');
await act(async () => button('Second').click());
Expand Down
Loading