Skip to content

[OPEND-4849] feat(motion): attribute installs through optional campaign links - #263

Draft
open-design-crew[bot] wants to merge 5 commits into
mainfrom
feat/motion-install-attribution
Draft

open-design-crew[bot] wants to merge 5 commits into
mainfrom
feat/motion-install-attribution

Conversation

@open-design-crew

@open-design-crew open-design-crew Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem and behavior

Campaign links currently lose their source when users install OpenMotion. Add optional setup --utm-source attribution, retaining the existing installation identity and saved source on untagged upgrades. Successful setup and subsequent domain events expose od_utm_source; existing telemetry opt-outs remain effective.

An R2-backed Worker annotates setup commands only when the published guide declares support. Untagged requests and older guides retain their commands. The Worker is deployed on its independent workers.dev endpoint; the test website route open-design.powerformer.net/motion/install.md is now enabled. Production routes remain disabled and no npm version was published by this change.

Validation

  • Tracking and guide compatibility: 12 tests passed.
  • Focused bundled setup and source persistence: 2 tests passed.
  • npm packaging: 8 tests passed; distribution: 2 tests passed.
  • Repository checks, tracking/Studio typechecks and Studio build passed.
  • Cloudflare deployment and direct R2 object read succeeded. The test website entry returns HTTP 200 with and without utm_source and matches the current R2 guide byte for byte. The independent workers.dev hostname times out from this machine.

Rollout

Publish a supporting installer to enable parameter injection on the existing test entry. Verify and activate the production website route separately. Immutable guides and other release resources remain on R2. See docs/install-attribution.md. Companion landing branch: feat/motion-install-attribution in core/od-landing.

@lefarcen
lefarcen requested a review from PerishCode November 11, 2026 08:02
@lefarcen lefarcen added size/M Medium change: 100-299 lines risk/medium Medium risk change type/feature Feature or new user-facing capability labels Nov 11, 2026
@lefarcen
lefarcen marked this pull request as ready for review November 11, 2026 08:23
@PerishCode

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #263 because this pull request has merge conflicts right now.

Please resolve the conflicts with feature/motion and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

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

lefarcen and others added 2 commits November 11, 2026 16:28
The tracked-source scan rejects full internal URLs, so the new attribution
doc and the eleven-locale prompt assertion failed the standalone job.
Keep the deployment entry as a bare hostname like the other docs, and assert
the setup URL with the regex form already used for the same host in this file.

Validation: gitleaks source scan passed (3349 files); release-scan,
release-workflows, registry-download and stable-release tests passed (35);
tests/catalog.test.ts passed (7); npm run check and typecheck:studio passed.

Generated-By: looper 0.16.2 (runner=fixer, agent=pi)

@PerishCode PerishCode left a comment

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.

The review found two installation compatibility and rollout issues that should be resolved before merging, plus a command-generation edge case. All 16 changed files were reviewed. The 58 focused tests, two selected packaging checks, repository checks, Studio typecheck/build, tracking compilation and diff whitespace check passed on the CI-pinned Node version. Browser, target-machine installation and external-service acceptance suites were not run. The initial pnpm preparation failed because this standalone npm repository has no pnpm lockfile; validation reused the existing npm dependencies.

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

Comment thread docs/install.md Resolved
Comment thread shared/integration.ts Resolved
Comment thread workers/install-guide/index.ts Resolved
…nabled entry

- Read the sealed installer from the candidate archive and drop the
  support marker when that exact installer does not accept
  --utm-source, so a guide built for an older integrated source never
  hands setup an unsupported flag.
- Keep prod template prompts on the existing R2 installation guide
  until the production website entry is activated and verified; only
  the enabled test entry moves to its environment host.
- Bind the injected campaign source with `=` so allowlisted values that
  start with a hyphen remain one option value.

Generated-By: looper 0.16.2 (runner=fixer, agent=pi)
@luogao

luogao commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Looper fixer round complete — 6509ce2

  • ✅ Review comment on docs/install.md:15 (@PerishCode) — thread
    • Guide generation now extracts package/scripts/npm-installer.mjs from the sealed tgz and emits the support marker only when that exact installer documents and parses utm-source, removing the marker otherwise (scripts/install-guide.mjs). Added a guide test that seals a legacy installer without the option and asserts the marker is absent, alongside a supported-installer case.
  • ✅ Review comment on shared/integration.ts (@PerishCode) — thread
  • ✅ Review comment on workers/install-guide/index.ts (@PerishCode) — thread
    • The Worker now emits --utm-source=${source} so allowlisted values that begin with a hyphen stay a single option value the installer accepts (workers/install-guide/index.ts). Added leading-hyphen regression cases (--help, -x) to tests/install-attribution-worker.test.ts and aligned docs/install-attribution.md.
  • 🔀 Merge conflict

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

@PerishCode PerishCode left a comment

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.

@app/open-design-crew The repair pass verifies all three previous findings: guide capability now follows the sealed installer, production prompts retain the active R2 guide, and leading-hyphen sources remain valid CLI values. I reviewed the nine-file delta since the previous reviewed head and its directly affected contracts and tests; no actionable findings remain in that scope. Thanks for the focused fixes and regression coverage.

On the CI-pinned Node version, 32 focused tests, repository checks, Studio typechecking/build, documentation links and diff whitespace checks passed. Dependency preparation used npm ci after the requested frozen pnpm install found no pnpm lockfile. The packaging checks passed after Studio build completed; their earlier attempt lacked that build output. GitHub reports no checks for this head. Browser, target-machine installation and external-service acceptance were not run.

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

@qd1993102

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #263 because this pull request has merge conflicts right now.

Please resolve the conflicts with feature/motion and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

@open-design-crew
open-design-crew Bot changed the base branch from feature/motion to main November 13, 2026 08:12
@lefarcen
lefarcen requested a review from PerishCode November 13, 2026 08:54
@PerishCode

Copy link
Copy Markdown
Contributor

@app/open-design-crew I'm holding off on generating review comments for #263 because this pull request has merge conflicts right now.

Please resolve the conflicts with main and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

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

@open-design-crew

Copy link
Copy Markdown
Contributor Author

What this change does: Adds optional install-source attribution and a read-only installation-guide Worker.

Integration blocker: a local three-way merge against main 31c14d85 confirms a conflict in tracking/node.ts and other changed files. The current head therefore has no validated final integration result and should not be approved for merging yet.

I inspected source validation, shell-safe option formatting and attribution privacy. No additional source defect is confirmed in that inspected scope. Resolve installer/distribution/tracking changes together. Preserve newer source-install guidance and the repository-template prompt path; verify the guide and installer agree on the optional flag without publishing or deploying the Worker as part of this review.

Verdict: Resolve the integration blocker and review/test the resulting head before merging.

Reviewed head 6509ce2f50aa1a74653a29d9771207e21be9b19a. This review does not claim a clean merged build, live agent/provider acceptance or a production security audit. No product changes, merge or publication were performed.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

What this change does: Adds optional install-source attribution and a read-only installation-guide Worker.

Follow-up review: the head is unchanged from the previous review. This pass rechecks applicability and integration against current main rather than repeating an unchanged full source review.

The current head still conflicts with main in scripts/distribution.ts, scripts/npm-installer.mjs, studio/src/motion/TemplateLibraryDialog.test.tsx, tests/install-guide.test.ts and other files. A local three-way merge reconfirmed this; a green historical head build does not verify the resolved integration.

Verdict: Resolve the current integration conflict and review/test the resulting head before approval.

No current-head CI checks are reported yet.

Reviewed head 6509ce2f50aa1a74653a29d9771207e21be9b19a against main 44aede36236a79c5f48bc0c7faf29ca7369b2a6d. No approval, merge or publication is performed by this review. No live PostHog ingestion, paid provider calls or real-host/human audiovisual acceptance was performed.

@qd1993102 qd1993102 left a comment

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.

@app/open-design-crew — reviewed the install-attribution change end to end: installer --utm-source handling, identity persistence, the tracking sender/registry wiring, guide generation, the new install-guide Worker, and the docs. One blocking issue: two studio tests embed the internal test host with a scheme, which the tracked-source scan rejects, so the PR's own standalone job fails at the scan step. One non-blocking note asks for a single assertion that the new installation_result event actually reaches the sender. Details inline.

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

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.

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.

@lefarcen
lefarcen marked this pull request as draft November 17, 2026 07:11
@lefarcen

Copy link
Copy Markdown
Contributor

Heads-up: PR #638 is also open for the same campaign-linked install attribution work, with overlapping installer, tracking, Worker, and regression-test files. Since both PRs are from the same contributor, would you like to consolidate them into one current branch? The maintainer team can then review a single integration result.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk/medium Medium risk change size/M Medium change: 100-299 lines type/feature Feature or new user-facing capability

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants