diff --git a/docs/contributing/unified-sharing-rollout.md b/docs/contributing/unified-sharing-rollout.md new file mode 100644 index 0000000000..cb51f8097e --- /dev/null +++ b/docs/contributing/unified-sharing-rollout.md @@ -0,0 +1,7 @@ +# Validate local sharing + +Run the share package, CLI, and Studio tests before publishing a change to the sharing flow. For manual verification, create a review link in the CLI, then open the same folder in local Studio and add a version. Verify that both surfaces reuse the existing link and that an interrupted upload can resume without creating another version. + +Check that copying an existing link leaves local edits untouched, that changing or disabling access preserves the expected link state, and that existing published links and updates continue to work. For accounts that support editable project files, verify that the source matches the rendered version and can be opened by an authorized recipient. + +Sharing telemetry uses the existing CLI preference. Verify that opting out suppresses events and that payloads contain no project paths, titles, review links, credentials, or raw errors. Upload admission, playback readiness, and copying a link are separate events. diff --git a/packages/cli/src/share/service.test.ts b/packages/cli/src/share/service.test.ts index abc9961556..6c755b83eb 100644 --- a/packages/cli/src/share/service.test.ts +++ b/packages/cli/src/share/service.test.ts @@ -11,6 +11,8 @@ const mocks = vi.hoisted(() => ({ add: vi.fn(), pending: vi.fn(), refresh: vi.fn(), + event: vi.fn(), + access: vi.fn(), })); vi.mock("@hyperframes/share", () => ({ reviewClient: () => ({ project: mocks.project, spaces: mocks.spaces, reviewFlags: mocks.flags }), @@ -33,7 +35,7 @@ vi.mock("@hyperframes/share", () => ({ }, })); vi.mock("./auth.js", () => ({ - createShareAccess: () => ({ access: vi.fn() }), + createShareAccess: () => ({ access: mocks.access }), shareSite: () => "https://hyperframes.dev", })); vi.mock("./host.js", () => ({ @@ -41,6 +43,11 @@ vi.mock("./host.js", () => ({ bindCliShareProject: (path: string) => path, })); vi.mock("./render.js", () => ({ prepareShareRender: mocks.render })); +vi.mock("../telemetry/client.js", () => ({ + trackEvent: mocks.event, + resetTelemetryPostureCache: vi.fn(), +})); +vi.mock("../telemetry/config.js", () => ({ readConfigFresh: vi.fn() })); import { createShareService } from "./service.js"; const shared = { projectId: "project", @@ -269,3 +276,115 @@ describe("asynchronous share recovery", () => { }); }); }); +describe("share rollout signals", () => { + const events = () => mocks.event.mock.calls.map(([name]) => name); + it("records a completed video even when its review link is disabled", async () => { + mocks.status.mockResolvedValue({ ...shared, url: null }); + mocks.add.mockImplementation(async (request) => request.onAdded()); + const result = await createShareService("/secret").run({ action: "update" }); + expect(result.state).toBe("link_off"); + expect(events()).toContain("share_video_ready"); + expect(events()).not.toContain("share_mutation_processing"); + }); + it("records the allowlisted missing-audience usage reason", async () => { + await expect(createShareService("/secret").run({ action: "share" })).rejects.toMatchObject({ + code: "audience_required", + }); + expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ reason: "audience_required" }); + }); + it("records recovery before refreshing a completed pending upload clears its state", async () => { + mocks.status.mockResolvedValue(shared); + mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" }); + mocks.refresh.mockImplementation(async () => mocks.pending.mockResolvedValue(null)); + await createShareService("/secret").run({ action: "share" }); + expect(events()).toContain("share_recovery_attempted"); + expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true }); + expect(events()).not.toContain("share_video_ready"); + expect(mocks.add).not.toHaveBeenCalled(); + }); + it("records only verified upload admission and ready, attributed to local Studio", async () => { + mocks.status.mockResolvedValue(shared); + mocks.add.mockImplementation(async (request) => { + request.onProgress({ step: "preparing", sent: 0, total: 0 }); + request.onProgress({ step: "uploading", sent: 1, total: 2 }); + request.onProgress({ step: "processing", sent: 2, total: 2 }); + request.onAdded(); + }); + await createShareService("/private/project", undefined, { surface: "local_studio" }).run({ + action: "update", + }); + expect(events()).toEqual([ + "share_mutation_attempted", + "share_mutation_authenticated", + "share_mutation_admitted", + "share_video_ready", + ]); + expect(mocks.event.mock.calls.every(([, data]) => data.client_surface === "local_studio")).toBe( + true, + ); + expect(new Set(mocks.event.mock.calls.map(([, data]) => data.attempt_id)).size).toBe(1); + }); + it("counts quota refusal without admission, rendering, or raw error details", async () => { + mocks.spaces.mockResolvedValue([ + { + space_id: "space", + bound: true, + can_create_review: true, + review_entitlements: { can_register_project: false }, + }, + ]); + await expect( + createShareService("/secret").run({ action: "share", audience: "public" }), + ).rejects.toBeDefined(); + expect(events()).toEqual([ + "share_mutation_attempted", + "share_mutation_authenticated", + "share_mutation_failed", + ]); + expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ + reason: "review_project_limit_reached", + }); + expect(mocks.render).not.toHaveBeenCalled(); + }); + it("records pending recovery without labeling the prior ready version new", async () => { + mocks.status.mockResolvedValue(shared); + mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" }); + mocks.add.mockResolvedValue(null); + mocks.version.mockResolvedValue({ last: { current: false }, source: "ready" }); + await createShareService("/secret").run({ action: "update" }); + expect(events()).toContain("share_recovery_attempted"); + expect(events()).toContain("share_mutation_processing"); + expect(events()).not.toContain("share_video_ready"); + expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true }); + }); + it("existing-link retrieval and polling never count as a new video or copied link", async () => { + mocks.status.mockResolvedValue(shared); + const service = createShareService("/secret"); + await service.run({ action: "status" }); + expect(events()).toEqual([]); + await service.run({ action: "share" }); + expect(events()).toEqual([ + "share_mutation_attempted", + "share_mutation_authenticated", + "share_existing_link_returned", + ]); + }); + it("stops entry creation on authoritative rollback while keeping existing links readable", async () => { + mocks.flags.mockResolvedValue({ versionSharing: false }); + await expect( + createShareService("/secret").run({ action: "share", audience: "public" }), + ).rejects.toMatchObject({ reason: "feature_unavailable" }); + expect(mocks.render).not.toHaveBeenCalled(); + expect(mocks.create).not.toHaveBeenCalled(); + mocks.status.mockResolvedValue(shared); + expect((await createShareService("/secret").run({ action: "share" })).ready).toBe(true); + }); +}); + +it("link reactivation cannot bypass the first-share rollout gate", async () => { + mocks.flags.mockResolvedValue({ versionSharing: false }); + await expect(createShareService("/secret").linkOn()).rejects.toMatchObject({ + reason: "not_shared", + }); + expect(mocks.create).not.toHaveBeenCalled(); +}); diff --git a/packages/cli/src/share/service.ts b/packages/cli/src/share/service.ts index 278e270f7c..2ce16b3dd7 100644 --- a/packages/cli/src/share/service.ts +++ b/packages/cli/src/share/service.ts @@ -21,6 +21,7 @@ import { createShareAccess, shareSite } from "./auth.js"; import { assertReviewUploadStorage, bindCliShareProject } from "./host.js"; import { prepareShareRender } from "./render.js"; import { prepareCliShareSource, uncheckedSource, type PreparedShareSource } from "./sources.js"; +import { observeShareMutation, type ShareAttempt, type ShareSurface } from "./telemetry.js"; export interface ShareAction { action: "share" | "update" | "status" | "manage"; @@ -34,10 +35,25 @@ function linkState(share: ReviewShare | null, ready: boolean): string { if (!share.url) return "link_off"; return ready ? "ready" : "processing"; } -async function readStatus(dir: string, client: ReviewClient, expectedProjectId?: string) { +async function refreshShare( + dir: string, + client: ReviewClient, + expectedProjectId?: string, + onRecovery?: (pending: boolean) => void, +) { const share = await reviewStatus({ projectPath: dir, client }); if (expectedProjectId) assertUploadProject(share, expectedProjectId); + if (onRecovery) onRecovery(isProcessing(await pendingReviewExport(dir), share)); if (share) await refreshReviewExport(dir, client); + return share; +} +async function readStatus( + dir: string, + client: ReviewClient, + expectedProjectId?: string, + onRecovery?: (pending: boolean) => void, +) { + const share = await refreshShare(dir, client, expectedProjectId, onRecovery); const project = await readProject(share, client); const latest = project?.latest_ready_version_id ?? null; const version = await reviewVersion(dir, { latestReadyVersionId: latest }); @@ -142,6 +158,7 @@ function assertResumeSource(current: ShareState, input: ShareAction) { export function createShareService( projectPath: string, progress: (value: ReviewExportProgress | null) => void = () => {}, + options: { surface?: ShareSurface } = {}, ) { const dir = bindCliShareProject(projectPath); const auth = createShareAccess(); @@ -150,7 +167,12 @@ export function createShareService( await auth.access(); return readStatus(dir, client, expectedProjectId); }; - const upload = async (input: ShareAction, projectId: string, sources: PreparedShareSource) => { + const upload = async ( + input: ShareAction, + projectId: string, + sources: PreparedShareSource, + attempt: ShareAttempt, + ) => { const end = Date.now() + (input.waitSeconds ?? 300) * 1000; let added = false; const failure = await addVersion({ @@ -158,7 +180,10 @@ export function createShareService( projectId, title: basename(dir), client, - onProgress: progress, + onProgress: (value) => { + attempt.progress(value); + progress(value); + }, allowPending: true, ...(sources.filesForExport && { filesForExport: sources.filesForExport }), requireSource: sources.requireSource, @@ -171,8 +196,11 @@ export function createShareService( if (failure) throw new Error(failure); const result = { ...(await status(projectId)), source: sources.source }; if (result.version.failure) throw new Error(result.version.failure); - if (!added && !result.version.last?.current) + if (!added && !result.version.last?.current) { + attempt.complete(false, added); return { ...result, state: "processing", ready: false, url: null }; + } + attempt.complete(result.ready, added); return result; }; const uploadTarget = async (current: ReviewShare | null, input: ShareAction, space?: string) => { @@ -204,11 +232,15 @@ export function createShareService( audience: target.audience, }); }; - const run = async (input: ShareAction) => { - const current = await status(); - if (input.action === "status" || input.action === "manage") return current; + const mutate = async (input: ShareAction, attempt: ShareAttempt) => { + await auth.access(); + attempt.authenticated(); + const current = await readStatus(dir, client, undefined, attempt.recover); assertExistingIntent(current.share, input); - if (retrievesExisting(current, input)) return current; + if (retrievesExisting(current, input)) { + attempt.retrieved(); + return current; + } const flags = await client.reviewFlags(); if (!flags.versionSharing) throw new ReviewFailed(403, "feature_unavailable"); const space = current.share @@ -223,11 +255,16 @@ export function createShareService( shareFiles: flags.shareFiles, }); if (sources.requireSource) await checkPreparedTarget(target); - return upload(input, target.projectId, sources); + return upload(input, target.projectId, sources, attempt); }; return { status, - run, + run: (input: ShareAction) => + input.action === "status" || input.action === "manage" + ? status() + : observeShareMutation(input.action, options.surface ?? "cli", (attempt) => + mutate(input, attempt), + ), capabilities: () => client.reviewFlags(), spaces: () => client.spaces(), setAccess: async (access: AccessMode) => { @@ -239,6 +276,7 @@ export function createShareService( return status(); }, linkOn: async () => { + if (!(await status()).share) throw new ReviewFailed(404, "not_shared"); await shareForReview({ projectPath: dir, title: basename(dir), client }); return status(); }, diff --git a/packages/cli/src/share/telemetry.optOut.test.ts b/packages/cli/src/share/telemetry.optOut.test.ts new file mode 100644 index 0000000000..855f541884 --- /dev/null +++ b/packages/cli/src/share/telemetry.optOut.test.ts @@ -0,0 +1,61 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ enqueue: vi.fn() })); +vi.mock("../telemetry/transport.js", () => ({ + enqueue: mocks.enqueue, + flush: vi.fn(), + flushSync: vi.fn(), +})); +vi.mock("../utils/env.js", () => ({ isDevMode: () => false })); +vi.mock("../telemetry/system.js", () => ({ getSystemMeta: () => ({}) })); +vi.mock("../telemetry/canary.js", () => ({ canaryEventProperties: () => ({}) })); +vi.mock("../telemetry/signedInUser.js", () => ({ signedInHeygenUsername: () => undefined })); +import { observeShareMutation, trackShareInteraction } from "./telemetry.js"; + +let folder: string; +function preference(enabled: boolean) { + writeFileSync( + join(folder, "config.json"), + JSON.stringify({ anonymousId: "test", bucketSeed: "test", telemetryEnabled: enabled }), + ); +} +beforeEach(() => { + mocks.enqueue.mockClear(); + folder = mkdtempSync(join(tmpdir(), "hf-share-opt-out-")); + vi.stubEnv("HYPERFRAMES_CONFIG_DIR", folder); + vi.stubEnv("HYPERFRAMES_NO_TELEMETRY", ""); + vi.stubEnv("DO_NOT_TRACK", ""); + preference(true); +}); +afterEach(() => { + vi.unstubAllEnvs(); + rmSync(folder, { recursive: true, force: true }); +}); + +it("stops queueing events after a separate process changes the persisted preference", async () => { + trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio"); + expect(mocks.enqueue).toHaveBeenCalledOnce(); + preference(false); + mocks.enqueue.mockClear(); + trackShareInteraction({ event: "share_link_copied", via: "copy" }, "local_studio"); + await observeShareMutation("update", "local_studio", async (attempt) => { + attempt.authenticated(); + attempt.complete(true, true); + }); + expect(mocks.enqueue).not.toHaveBeenCalled(); +}); + +it.each(["HYPERFRAMES_NO_TELEMETRY", "DO_NOT_TRACK"])( + "honors %s even after a previous event enabled the client cache", + async (name) => { + trackShareInteraction({ event: "share_opened", link: "none" }); + expect(mocks.enqueue).toHaveBeenCalledOnce(); + vi.stubEnv(name, "1"); + mocks.enqueue.mockClear(); + await observeShareMutation("share", "cli", async (attempt) => attempt.complete(true, true)); + expect(mocks.enqueue).not.toHaveBeenCalled(); + }, +); diff --git a/packages/cli/src/share/telemetry.test.ts b/packages/cli/src/share/telemetry.test.ts new file mode 100644 index 0000000000..732d6a9e66 --- /dev/null +++ b/packages/cli/src/share/telemetry.test.ts @@ -0,0 +1,49 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +const mocks = vi.hoisted(() => ({ track: vi.fn(), fresh: vi.fn(), reset: vi.fn() })); +vi.mock("../telemetry/client.js", () => ({ + trackEvent: mocks.track, + resetTelemetryPostureCache: mocks.reset, +})); +vi.mock("../telemetry/config.js", () => ({ readConfigFresh: mocks.fresh })); +import { observeShareMutation, trackShareInteraction } from "./telemetry.js"; +beforeEach(() => vi.resetAllMocks()); +describe("share telemetry privacy boundary", () => { + it("only forwards the declared interaction fields, never links or project data", () => { + const input = { + event: "share_link_copied" as const, + via: "copy" as const, + url: "https://private/token", + project: "/example/project", + }; + trackShareInteraction(input, "local_studio"); + expect(mocks.track).toHaveBeenCalledExactlyOnceWith("share_link_copied", { + client_surface: "local_studio", + via: "copy", + }); + }); + it("refreshes persisted opt-out posture at each event in a long-lived preview", () => { + trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio"); + trackShareInteraction({ event: "share_link_copied", via: "publish" }, "local_studio"); + expect(mocks.fresh).toHaveBeenCalledTimes(2); + expect(mocks.reset).toHaveBeenCalledTimes(2); + }); + it("drops unknown failure reasons and never sends raw messages", async () => { + const error = Object.assign(new Error("secret email@example.com"), { + reason: "/secret/project", + }); + await expect( + observeShareMutation("update", "cli", async () => { + throw error; + }), + ).rejects.toBe(error); + expect(mocks.track.mock.lastCall?.[1]).toMatchObject({ reason: "other" }); + expect(JSON.stringify(mocks.track.mock.calls)).not.toContain("secret"); + }); + it("telemetry configuration errors cannot block sharing or change its failure", async () => { + mocks.fresh.mockImplementation(() => { + throw new Error("EACCES"); + }); + expect(await observeShareMutation("share", "cli", async () => "done")).toBe("done"); + expect(mocks.track).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/cli/src/share/telemetry.ts b/packages/cli/src/share/telemetry.ts new file mode 100644 index 0000000000..3852cb8d20 --- /dev/null +++ b/packages/cli/src/share/telemetry.ts @@ -0,0 +1,96 @@ +import { randomUUID } from "node:crypto"; +import { AuthError } from "../auth/errors.js"; +import { CliUsageError } from "../utils/commandResult.js"; +import { readConfigFresh } from "../telemetry/config.js"; +import { resetTelemetryPostureCache, trackEvent } from "../telemetry/client.js"; +import type { ReviewExportProgress } from "@hyperframes/share"; + +export type ShareSurface = "cli" | "local_studio"; +export type ShareInteraction = + | { event: "share_opened"; link: "none" | "live" | "changed" } + | { event: "share_link_copied"; via: "copy" | "publish" | "update" }; +const REASONS = new Set([ + "feature_unavailable", + "audience_required", + "workspace_cannot_share", + "workspace_mismatch", + "manage_existing_audience", + "review_project_limit_reached", + "review_subscription_required", + "review_entitlement_unavailable", + "review_public_consent_required", + "moderation_hold", + "review_operation_busy", + "not_shared", + "offline", + "signed_out", +]); +function failureReason(error: unknown): string { + if (error instanceof AuthError) return "authentication"; + if (error instanceof CliUsageError && REASONS.has(error.code)) return error.code; + if (typeof error === "object" && error !== null && "reason" in error) { + const reason = error.reason; + if (typeof reason === "string" && REASONS.has(reason)) return reason; + } + return "other"; +} +function emit(event: string, properties: Record): void { + try { + // A preview process can outlive an opt-out made from another terminal. + readConfigFresh(); + resetTelemetryPostureCache(); + trackEvent(event, properties); + } catch { + // Telemetry must not alter whether a share succeeds or fails. + } +} +export function trackShareInteraction(input: ShareInteraction, surface: ShareSurface = "cli") { + if (input.event === "share_opened") + emit(input.event, { client_surface: surface, link: input.link }); + else emit(input.event, { client_surface: surface, via: input.via }); +} +function shareAttempt(action: "share" | "update", surface: ShareSurface) { + const base = { client_surface: surface, action, attempt_id: randomUUID() }; + let admitted = false; + let recovery = false; + const track = (event: string, extra: Record = {}) => + emit(event, { ...base, recovery, ...extra }); + const admit = () => { + if (admitted) return; + admitted = true; + track("share_mutation_admitted"); + }; + track("share_mutation_attempted"); + return { + authenticated: () => track("share_mutation_authenticated"), + recover: (pending: boolean) => { + recovery = pending; + if (pending) track("share_recovery_attempted"); + }, + progress: (value: ReviewExportProgress | null) => { + if (value && value.step !== "preparing") admit(); + }, + retrieved: () => track("share_existing_link_returned"), + complete: (ready: boolean, added: boolean) => { + if (!added) + return track(ready ? "share_existing_link_returned" : "share_mutation_processing"); + admit(); + track("share_video_ready"); + }, + failed: (error: unknown) => track("share_mutation_failed", { reason: failureReason(error) }), + }; +} +export type ShareAttempt = ReturnType; +export async function observeShareMutation( + action: "share" | "update", + surface: ShareSurface, + run: (attempt: ShareAttempt) => Promise, +): Promise { + const attempt = shareAttempt(action, surface); + try { + return await run(attempt); + } catch (error) { + attempt.failed(error); + throw error; + } +}