Skip to content

Commit 0ca6947

Browse files
feat(cli): feedback says whether a person or an agent wrote it, with the email an app attaches (#4984)
* feat(cli): feedback says whether a person or an agent wrote it, with the email an app attaches * refactor(cli): split the .env loader so each part stays simple * fix(cli): a broken .env loader fails loudly; only a missing .env is ignored
1 parent de9bf48 commit 0ca6947

11 files changed

Lines changed: 171 additions & 35 deletions

File tree

‎docs/guides/feedback.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ Do not include API keys, access tokens, credentials, private media, or customer
6262

6363
HyperFrames may occasionally show a short rating prompt after a render or during a Studio session. You can ignore or dismiss it.
6464

65-
Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values beyond the short agent and app names listed under [`telemetry`](/packages/cli#telemetry), such as `client=example-app/1.2.3/stable` when another app launched the CLI.
65+
Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values beyond the short agent and app names listed under [`telemetry`](/packages/cli#telemetry), such as `client=example-app/1.2.3/stable` when another app launched the CLI. When an app launches it for a signed-in person, the report can also carry that person's email, set by the app through `HYPERFRAMES_FEEDBACK_EMAIL`, and whether a person or an agent wrote it.
6666

6767
To turn off CLI telemetry:
6868

‎docs/packages/cli.mdx‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1232,15 +1232,18 @@ Topics: `data-attributes`, `examples`, `rendering`, `gsap`, `troubleshooting`,
12321232

12331233
### `feedback`
12341234

1235-
Send anonymous feedback about how it went.
1235+
Send feedback about how it went. It is anonymous unless the app that launched
1236+
the CLI attaches your email (below).
12361237

12371238
```bash
12381239
npx hyperframes feedback --rating 10
12391240
npx hyperframes feedback --rating 7 --comment "render succeeded but GSAP timeline didn't animate"
12401241
npx hyperframes feedback --rating 3 --comment "GSAP timeline froze on seek" --file-issue
12411242
```
12421243

1243-
`--rating` is required, 0–10. `--comment` adds free text. `--file-issue`
1244+
`--rating` is required, 0–10. `--comment` adds free text. `--source person`
1245+
or `--source agent` says who wrote a rating report (a `--search-miss` report
1246+
carries neither), so the team can tell a person's feedback from an agent's. `--file-issue`
12441247
also opens a GitHub issue, `--dir` picks the project published as its repro
12451248
(default: current directory), and `--yes, -y` skips the consent prompt for
12461249
scripts.
@@ -1252,7 +1255,12 @@ submit yourself. No token, no backend. See
12521255

12531256
Agents can call this after a render;
12541257
[About feedback data](/guides/feedback#about-feedback-data) covers what the
1255-
surface includes. With telemetry disabled it prints
1258+
surface includes. An app that launches the CLI can attach its signed-in
1259+
person's email with the `HYPERFRAMES_FEEDBACK_EMAIL` environment variable. It
1260+
is never a flag and never read from a project `.env`, and it goes only into
1261+
the feedback report, not telemetry. It is not verified: treat it as a way to
1262+
reply, not as proof of who sent the report. With
1263+
telemetry disabled it prints
12561264
`Telemetry is disabled. Feedback not sent.` and exits cleanly.
12571265

12581266
### `telemetry`

‎packages/cli/src/cli.ts‎

Lines changed: 2 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -63,35 +63,12 @@ if (rootVersionRequested) {
6363
// ── Load .env from CWD ─────────────────────────────────────────────────────
6464
// Agents run from the project directory where .env holds API keys (Gemini,
6565
// HeyGen, ElevenLabs). Load it automatically so they don't need `source .env`.
66+
const { applyDotEnv } = await import("./utils/dotEnv.js");
6667
try {
6768
const { readFileSync } = await import("node:fs");
6869
const { resolve } = await import("node:path");
6970
const envPath = resolve(process.cwd(), ".env");
70-
const envContent = readFileSync(envPath, "utf-8");
71-
for (const rawLine of envContent.split("\n")) {
72-
let line = rawLine.trim();
73-
if (!line || line.startsWith("#")) continue;
74-
// Tolerate `export FOO=bar` (common in dotfile-style .env files).
75-
if (line.startsWith("export ")) line = line.slice(7).trim();
76-
const eqIdx = line.indexOf("=");
77-
if (eqIdx < 1) continue;
78-
const key = line.slice(0, eqIdx).trim();
79-
let val = line.slice(eqIdx + 1).trim();
80-
if (val.startsWith('"') || val.startsWith("'")) {
81-
// Quoted value: take until the matching closing quote; leave the rest.
82-
// Anything after a closing quote (including `# comment`) is dropped.
83-
const quote = val.charAt(0);
84-
const end = val.indexOf(quote, 1);
85-
if (end > 0) val = val.slice(1, end);
86-
else val = val.slice(1); // unterminated quote — best-effort, strip opener
87-
} else {
88-
// Unquoted value: strip inline `# comment` (requires whitespace before #
89-
// to avoid eating `pass#word` style values).
90-
const commentMatch = val.match(/\s+#/);
91-
if (commentMatch?.index !== undefined) val = val.slice(0, commentMatch.index).trim();
92-
}
93-
if (key && !(key in process.env)) process.env[key] = val;
94-
}
71+
applyDotEnv(readFileSync(envPath, "utf-8"), process.env);
9572
} catch {
9673
/* .env not present — fine, env vars may be set another way */
9774
}

‎packages/cli/src/commands/feedback.test.ts‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
1-
import { expect, it, vi } from "vitest";
1+
import { afterEach, expect, it, vi } from "vitest";
22

33
const mocks = vi.hoisted(() => ({
44
// Never settles: waiting on it would hang the command.
55
flush: vi.fn(() => new Promise<void>(() => {})),
6-
submitFeedback: vi.fn(async () => {}),
6+
submitFeedback: vi.fn(async (_input: { env?: string }) => {}),
77
submitCatalogSearchMiss: vi.fn(async () => {}),
88
}));
99
vi.mock("../telemetry/client.js", () => ({ shouldTrack: () => true, flush: mocks.flush }));
10+
const trackRenderFeedback = vi.hoisted(() => vi.fn());
1011
vi.mock("../telemetry/events.js", () => ({
1112
trackCatalogSearchMiss: vi.fn(),
12-
trackRenderFeedback: vi.fn(),
13+
trackRenderFeedback,
1314
}));
14-
vi.mock("../telemetry/feedback.js", () => ({ getDoctorSummary: async () => "" }));
15+
vi.mock("../telemetry/feedback.js", () => ({ getDoctorSummary: async () => "os=test" }));
16+
17+
afterEach(() => vi.unstubAllEnvs());
1518
vi.mock("../telemetry/config.js", () => ({ readConfig: () => ({ anonymousId: "a" }) }));
1619
vi.mock("../utils/submitFeedback.js", () => ({
1720
submitFeedback: mocks.submitFeedback,
@@ -27,3 +30,31 @@ it.each([
2730
await feedback.run?.({ args } as never);
2831
expect(submit).toHaveBeenCalled();
2932
});
33+
34+
it("tells person feedback from agent feedback, with the email only an app's env can attach", async () => {
35+
vi.spyOn(console, "log").mockImplementation(() => {});
36+
vi.stubEnv("HYPERFRAMES_FEEDBACK_EMAIL", " [email protected] ");
37+
const { default: feedback } = await import("./feedback.js");
38+
await feedback.run?.({ args: { rating: "6", comment: "hi", source: "person" } } as never);
39+
expect(mocks.submitFeedback).toHaveBeenLastCalledWith(
40+
expect.objectContaining({ source: "person", email: "[email protected]" }),
41+
);
42+
// The email goes only into the report: never telemetry, never the environment summary.
43+
expect(JSON.stringify(trackRenderFeedback.mock.calls)).not.toContain("[email protected]");
44+
expect(JSON.stringify(mocks.submitFeedback.mock.lastCall?.[0].env)).not.toContain(
45+
46+
);
47+
vi.unstubAllEnvs();
48+
await feedback.run?.({ args: { rating: "6", source: "agent" } } as never);
49+
expect(mocks.submitFeedback).toHaveBeenLastCalledWith(
50+
expect.objectContaining({ source: "agent", email: undefined }),
51+
);
52+
});
53+
54+
it("refuses a source that is neither person nor agent, and sends nothing", async () => {
55+
vi.spyOn(console, "error").mockImplementation(() => {});
56+
mocks.submitFeedback.mockClear();
57+
const { default: feedback } = await import("./feedback.js");
58+
await expect(feedback.run?.({ args: { rating: "6", source: "bot" } } as never)).rejects.toThrow();
59+
expect(mocks.submitFeedback).not.toHaveBeenCalled();
60+
});

‎packages/cli/src/commands/feedback.ts‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import { buildIssueUrl, HYPERFRAMES_REPO_URL } from "../utils/feedbackIssue.js";
1515
import { VERSION } from "../version.js";
1616
import { c } from "../ui/colors.js";
1717
import { parseFeedbackRating } from "../utils/feedbackRating.js";
18+
import { feedbackEmail, parseFeedbackSource } from "../utils/feedbackSource.js";
1819
import { lintFeedbackComment, type FeedbackLintInput } from "../utils/feedbackLint.js";
1920

2021
export const examples: Example[] = [
@@ -155,7 +156,7 @@ async function fileGithubIssue(opts: {
155156
}
156157

157158
export default defineCommand({
158-
meta: { name: "feedback", description: "Submit anonymous feedback about your experience" },
159+
meta: { name: "feedback", description: "Submit feedback about your experience" },
159160
args: {
160161
rating: {
161162
type: "string",
@@ -167,6 +168,10 @@ export default defineCommand({
167168
type: "string",
168169
description: "Optional details about your experience",
169170
},
171+
source: {
172+
type: "string",
173+
description: 'Who wrote the report: "person" or "agent"',
174+
},
170175
"search-miss": {
171176
type: "string",
172177
description: "Report a catalog search that found nothing useful; pass the query you ran",
@@ -223,6 +228,12 @@ export default defineCommand({
223228
failCommand();
224229
}
225230

231+
const source = parseFeedbackSource(args.source);
232+
if (source === null) {
233+
console.error(c.error('Source must be "person" or "agent"'));
234+
failCommand();
235+
}
236+
226237
if (!shouldTrack()) {
227238
console.log(c.dim("Telemetry is disabled. Feedback not sent."));
228239
return;
@@ -261,7 +272,14 @@ export default defineCommand({
261272
// Ack first so the user isn't kept waiting on the best-effort forward (which
262273
// is bounded to a few seconds and never surfaces an error either way).
263274
console.log(c.dim("Thanks for the feedback!"));
264-
await submitFeedback({ rating, comment, cliVersion: VERSION, env: envWithJoinKeys });
275+
await submitFeedback({
276+
rating,
277+
comment,
278+
cliVersion: VERSION,
279+
env: envWithJoinKeys,
280+
source,
281+
email: feedbackEmail(),
282+
});
265283

266284
if (args["file-issue"] === true) {
267285
await fileGithubIssue({
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { describe, expect, it } from "vitest";
2+
import { applyDotEnv } from "./dotEnv.js";
3+
4+
describe("applyDotEnv", () => {
5+
it("copies a project's keys without overwriting what is already set", () => {
6+
const env: NodeJS.ProcessEnv = { KEPT: "outer" };
7+
applyDotEnv('export GEMINI_KEY="abc" # note\nKEPT=inner\n# comment\nPLAIN=x #c', env);
8+
expect(env).toEqual({ KEPT: "outer", GEMINI_KEY: "abc", PLAIN: "x" });
9+
});
10+
11+
it("never takes the feedback email from a project file", () => {
12+
const env: NodeJS.ProcessEnv = {};
13+
applyDotEnv("[email protected]\nOTHER=1", env);
14+
expect(env).toEqual({ OTHER: "1" });
15+
});
16+
});

‎packages/cli/src/utils/dotEnv.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { FEEDBACK_EMAIL_ENV } from "./feedbackSource.js";
2+
3+
// A quoted value ends at its closing quote; unquoted, `#` starts a comment only after whitespace, so `pass#word` stays.
4+
function valueOf(raw: string): string {
5+
const quote = raw.charAt(0);
6+
if (quote === '"' || quote === "'") {
7+
const end = raw.indexOf(quote, 1);
8+
return end > 0 ? raw.slice(1, end) : raw.slice(1);
9+
}
10+
const comment = raw.match(/\s+#/);
11+
return comment?.index === undefined ? raw : raw.slice(0, comment.index).trim();
12+
}
13+
14+
function entryOf(rawLine: string): [string, string] | null {
15+
let line = rawLine.trim();
16+
if (!line || line.startsWith("#")) return null;
17+
if (line.startsWith("export ")) line = line.slice(7).trim();
18+
const eq = line.indexOf("=");
19+
if (eq < 1) return null;
20+
return [line.slice(0, eq).trim(), valueOf(line.slice(eq + 1).trim())];
21+
}
22+
23+
// Never over a key already set, and never the feedback email: only the launching app may attach it, and an agent can
24+
// write a project `.env`.
25+
export function applyDotEnv(content: string, env: NodeJS.ProcessEnv): void {
26+
for (const entry of content.split("\n").map(entryOf)) {
27+
if (!entry) continue;
28+
const [key, value] = entry;
29+
if (key && key !== FEEDBACK_EMAIL_ENV && !(key in env)) env[key] = value;
30+
}
31+
}
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { describe, expect, it } from "vitest";
2+
import { feedbackEmail, parseFeedbackSource } from "./feedbackSource.js";
3+
4+
describe("parseFeedbackSource", () => {
5+
it.each([
6+
[undefined, undefined],
7+
["person", "person"],
8+
[" agent ", "agent"],
9+
["Person", null],
10+
["", null],
11+
])("%j reads as %j", (raw, expected) => {
12+
expect(parseFeedbackSource(raw)).toBe(expected);
13+
});
14+
});
15+
16+
describe("feedbackEmail", () => {
17+
it("reads only HYPERFRAMES_FEEDBACK_EMAIL, trimmed, and nothing when blank", () => {
18+
expect(feedbackEmail({ HYPERFRAMES_FEEDBACK_EMAIL: " [email protected] " })).toBe("[email protected]");
19+
expect(feedbackEmail({ HYPERFRAMES_FEEDBACK_EMAIL: " " })).toBeUndefined();
20+
expect(feedbackEmail({ EMAIL: "[email protected]" })).toBeUndefined();
21+
});
22+
});
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
export type FeedbackSource = "person" | "agent";
2+
3+
const SOURCES: readonly string[] = ["person", "agent"];
4+
5+
/** The `--source` value, undefined when absent, null when it is neither. */
6+
export function parseFeedbackSource(raw: string | undefined): FeedbackSource | null | undefined {
7+
if (raw === undefined) return undefined;
8+
const source = raw.trim();
9+
return SOURCES.includes(source) ? (source as FeedbackSource) : null;
10+
}
11+
12+
export const FEEDBACK_EMAIL_ENV = "HYPERFRAMES_FEEDBACK_EMAIL";
13+
14+
/** Set only by the launching app (never a flag or a project `.env`); unverified, so never proof of identity. */
15+
export function feedbackEmail(env: NodeJS.ProcessEnv = process.env): string | undefined {
16+
return env[FEEDBACK_EMAIL_ENV]?.trim() || undefined;
17+
}

‎packages/cli/src/utils/submitFeedback.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,17 @@ describe("submitFeedback", () => {
4848
);
4949
});
5050

51+
it("sends who wrote it and the attached email, the email capped like the backend's", async () => {
52+
const fetchMock = vi.fn<typeof fetch>(async () => new Response(null, { status: 202 }));
53+
vi.stubGlobal("fetch", fetchMock);
54+
55+
await submitFeedback({ rating: 5, cliVersion: "1", source: "person", email: "e".repeat(300) });
56+
57+
const body = JSON.parse(fetchMock.mock.calls[0]?.[1]?.body as string);
58+
expect(body.source).toBe("person");
59+
expect(body.email).toHaveLength(254);
60+
});
61+
5162
it.each([0, 10])("serializes the NPS boundary %i without changing it", async (rating) => {
5263
const fetchMock = vi.fn<typeof fetch>(async () => new Response(null, { status: 202 }));
5364
vi.stubGlobal("fetch", fetchMock);

0 commit comments

Comments
 (0)