Files
hyperframes/packages/cli/src/commands/feedback.ts
T
James RussoandClaude Opus 5.5 22b615f1a7 fix(cli): files from outside the project are uploaded only once approved (#7995)
* fix(cli): files from outside the project are uploaded only once approved

publish, cloud render and feedback --file-issue copied every image, video, audio,
font and CSS file a composition named from outside the project folder, and every
project file that links outside it, and only listed them. A project that came from
someone else could pull a file from anywhere on the uploader's disk into an upload.

Now each such file needs approval. In a terminal the command lists them and asks,
defaulting to no; a yes is remembered per project in the CLI's config folder
(~/.hyperframes/outside-files.json), never in the project. --yes, --json, --dry-run
and unattended runs leave them out with a warning naming each file and saying how
to include it. --include-outside-files uploads them without asking.

— Rames

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(cli): check the approvals file mode only where files have POSIX modes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 03:34:57 +00:00

405 lines
14 KiB
TypeScript

import { failUsage } from "../utils/commandResult.js";
import { randomUUID } from "node:crypto";
import { resolve } from "node:path";
import { defineCommand } from "../utils/defineCommand.js";
import * as clack from "../ui/prompts.js";
import open from "open";
import type { Example } from "./_examples.js";
import {
trackCatalogSearchMiss,
trackFeedbackComment,
trackRenderFeedback,
} from "../telemetry/events.js";
import { shouldTrack } from "../telemetry/client.js";
import { getDoctorSummary } from "../telemetry/feedback.js";
import { readConfig, type LastCheckRecord, type RecentRenderRecord } from "../telemetry/config.js";
import { createPublishArchive, publishProjectArchive } from "../utils/publishProject.js";
import { submitCatalogSearchMiss, submitFeedback } from "../utils/submitFeedback.js";
import { buildIssueUrl, HYPERFRAMES_REPO_URL } from "../utils/feedbackIssue.js";
import { VERSION } from "../version.js";
import { c } from "../ui/colors.js";
import { isUnattended } from "../utils/attendedTerminal.js";
import { parseFeedbackRating } from "../utils/feedbackRating.js";
import { feedbackEmail, parseFeedbackSource } from "../utils/feedbackSource.js";
import { lintFeedbackComment, type FeedbackLintInput } from "../utils/feedbackLint.js";
import { type LeftOutReference, outsideFilesNotice } from "../utils/leftOutReference.js";
import { trackUploadLeftOut } from "../telemetry/uploadLeftOut.js";
import {
confirmOutsideFiles,
type OutsideFileChoice,
stageWithOutsideFileApproval,
} from "../utils/outsideFileApproval.js";
export const examples: Example[] = [
["Submit render feedback", 'hyperframes feedback --rating 8 --comment "fast but font missing"'],
["Quick rating only", "hyperframes feedback --rating 10"],
[
"Report something you needed that is missing (no rating)",
'hyperframes feedback --comment "MISSING FEATURE: trim a clip from the timeline | WORKAROUND: none"',
],
[
"Report a catalog gap after a fruitless search",
'hyperframes feedback --search-miss "typewriter that deletes" --wanted "text that types then backspaces"',
],
[
"Also file a GitHub issue with a published repro",
'hyperframes feedback --rating 3 --comment "GSAP timeline froze" --file-issue',
],
];
function normalizeComment(raw?: string): string | undefined {
return raw || undefined;
}
/**
* Compact PostHog join keys appended to the environment string that rides
* along with the forwarded report (and therefore lands verbatim in the wild
* feedback channel): `fid` = the PostHog `feedback_id` (`cli_render_feedback` or
* `cli_feedback_comment`); `tid` = the install's telemetry distinct_id; `renders` =
* recent `render_job_id`s (newest last, `!` suffix = the render failed).
* Together they turn a wild report into an exact telemetry lookup instead of
* a hardware-fingerprint hunt.
*/
export function buildTelemetryJoinKeys(input: {
feedbackId: string;
anonymousId: string;
recentRenders?: RecentRenderRecord[];
lastCheck?: LastCheckRecord;
now?: number;
}): string {
const parts = [`fid=${input.feedbackId}`, `tid=${input.anonymousId}`];
if (input.recentRenders?.length) {
parts.push(`renders=${input.recentRenders.map((r) => `${r.id}${r.ok ? "" : "!"}`).join(",")}`);
}
if (input.lastCheck) {
const codes = Object.entries(input.lastCheck.codes).map(
([code, n]) => `${code.slice(0, 24)}*${n}`,
);
const result =
input.lastCheck.exitCode === undefined ? "unfinished" : `exit${input.lastCheck.exitCode}`;
parts.push(`check=${result}${codes.length ? `:${codes.join(",")}` : ""}`);
const minutes = Math.round(
((input.now ?? Date.now()) - Date.parse(input.lastCheck.at)) / 60_000,
);
if (Number.isFinite(minutes) && minutes >= 0) parts.push(`check_age=${minutes}m`);
}
return parts.join(" ");
}
function printIssueConsent(dir: string): void {
console.log();
console.log(
` ${c.bold("Filing an issue will publish this project publicly and open a GitHub issue draft.")}`,
);
console.log(` ${c.dim(`Project at ${dir} will be uploaded to a public URL.`)}`);
console.log(
` ${c.dim("The issue draft will contain that public link plus your feedback; you review and submit it.")}`,
);
console.log();
}
async function promptConfirm(): Promise<boolean> {
const approved = await clack.confirm({ message: "Publish this project and draft the issue?" });
return !clack.isCancel(approved) && approved === true;
}
/**
* Consent gate: publishing uploads the project to a PUBLIC url, so confirm
* before proceeding. Returns true when the caller may publish + file.
*/
async function confirmFileIssue(dir: string, yes: boolean): Promise<boolean> {
printIssueConsent(dir);
if (yes) return true;
if (isUnattended()) {
console.log(` ${c.dim("Re-run with --yes to publish the repro and file the issue.")}\n`);
return false;
}
if (await promptConfirm()) return true;
console.log(`\n ${c.dim("Aborted. Feedback was still sent.")}\n`);
return false;
}
/**
* Publish a minimal repro and return its public URL. Degrades gracefully:
* on failure it returns undefined so the issue still opens without a link.
*/
async function publishRepro(
dir: string,
outsideFileChoice: OutsideFileChoice,
): Promise<string | undefined> {
const spinner = clack.spinner();
spinner.start("Publishing minimal repro...");
try {
const ask = outsideFileChoice.ask;
const { staged, outsideFiles } = await stageWithOutsideFileApproval(
dir,
{
...outsideFileChoice,
ask:
ask &&
((files) => {
spinner.stop("Repro prepared");
return ask(files).finally(() => spinner.start("Publishing minimal repro..."));
}),
},
(onOutsideFile) => {
const leftOut: string[] = [];
const references: LeftOutReference[] = [];
const archive = createPublishArchive(
dir,
(warning, reference) => {
leftOut.push(warning);
references.push(reference);
},
onOutsideFile,
);
return { archive, leftOut, references };
},
);
const { archive, leftOut, references } = staged;
trackUploadLeftOut("feedback", references);
if (outsideFiles.length > 0) {
spinner.stop("Repro prepared");
clack.log.info(outsideFilesNotice(outsideFiles));
spinner.start("Publishing minimal repro...");
}
const published = await publishProjectArchive(dir, { archive });
spinner.stop(c.success("Repro published"));
for (const warning of leftOut) clack.log.warn(c.warn(warning));
return published.url;
} catch (err: unknown) {
spinner.stop(c.error("Publish failed"));
console.error(` ${(err as Error).message}`);
console.log(` ${c.dim("Filing the issue without a repro link.")}`);
return undefined;
}
}
/**
* Print soft-warn feedback-lint messages to stdout. Extracted so the
* command's `run` stays a flat control-flow driver — the warning loop is
* incidental to the command logic and its complexity would otherwise push
* `run` over the Fallow CRAP threshold.
*/
function printFeedbackLintWarnings(input: FeedbackLintInput): void {
for (const warning of lintFeedbackComment(input)) {
console.log(c.warn(`⚠ ${warning.message}`));
}
}
async function openAndPrintIssue(url: string): Promise<void> {
if (process.stdout.isTTY) {
try {
await open(url);
} catch {
// Headless or no browser; the printed URL below is the fallback.
}
}
console.log();
console.log(` ${c.dim("Review and submit the pre-filled issue (it is not auto-submitted):")}`);
console.log(` ${c.accent(url)}`);
console.log();
}
async function fileGithubIssue(opts: {
rating: number;
comment?: string;
rawDir?: string;
yes: boolean;
includeOutsideFiles: boolean;
doctorSummary: string;
}): Promise<void> {
const dir = resolve(opts.rawDir ?? ".");
if (!(await confirmFileIssue(dir, opts.yes))) return;
const repoPublicUrl = await publishRepro(dir, {
includeAll: opts.includeOutsideFiles,
ask: opts.yes || isUnattended() ? undefined : confirmOutsideFiles,
});
const url = buildIssueUrl({
repoUrl: HYPERFRAMES_REPO_URL,
rating: opts.rating,
comment: opts.comment,
repoPublicUrl,
environment: opts.doctorSummary,
cliVersion: VERSION,
});
await openAndPrintIssue(url);
}
// A comment with no rating is its own report (a missing feature, host-app
// friction): it scores nothing, so it must stay out of the rating metric.
function reportRating(
raw: string | undefined,
comment: string | undefined,
fileIssue: boolean,
): number | undefined {
const rating = raw === undefined ? undefined : parseFeedbackRating(raw);
if (rating === null) {
console.error(c.error("Rating must be an integer between 0 and 10"));
failUsage();
}
if (rating === undefined && !comment?.trim()) {
console.error(c.error("Give a --rating (an integer from 0 to 10), a --comment, or both"));
failUsage();
}
if (rating === undefined && fileIssue) {
console.error(c.error("--file-issue needs a --rating"));
failUsage();
}
return rating;
}
function trackFeedback(report: {
rating: number | undefined;
comment: string | undefined;
doctorSummary: string;
feedbackId: string;
recentRenderIds: string[] | undefined;
}): void {
const { rating, comment, ...keys } = report;
if (rating === undefined) {
if (comment) trackFeedbackComment({ comment, ...keys });
return;
}
// Soft-warn (never blocks) when the comment for a non-clean report is
// missing the mandated reproduction-packet markers. Prints before the
// submission ack so the reporter sees the nudge while their run is fresh.
printFeedbackLintWarnings({ rating, comment });
// The standalone command runs separately from `render`, so it has no real
// elapsed time to report. Omit it rather than recording a fake duration.
trackRenderFeedback({ rating, comment, ...keys });
}
export default defineCommand({
meta: { name: "feedback", description: "Submit feedback about your experience" },
args: {
rating: {
type: "string",
// Optional: --search-miss and a lone --comment are reports with no
// rating to give, so the check lives in the run body.
description: "Likelihood to recommend (0=not likely, 10=extremely likely)",
},
comment: {
type: "string",
description: "Details about your experience; alone, a report with no rating",
},
source: {
type: "string",
description: 'Who wrote the report: "person" or "agent"',
},
"search-miss": {
type: "string",
description: "Report a catalog search that found nothing useful; pass the query you ran",
},
wanted: {
type: "string",
description: "What you needed the catalog to have (used with --search-miss)",
},
tier: {
type: "string",
description: 'Which search tier answered: "on-device" or "words"',
},
"file-issue": {
type: "boolean",
description: "Also open a pre-filled GitHub issue with a published minimal repro",
default: false,
},
dir: {
type: "string",
description: "Project directory to publish as the repro (default: current directory)",
},
yes: {
type: "boolean",
alias: "y",
description: "Skip the publish + file-issue consent prompt",
default: false,
},
"include-outside-files": {
type: "boolean",
description:
"Upload the files the repro uses from outside its folder without asking. Otherwise they are left out unless you approve them.",
default: false,
},
},
async run({ args }) {
// A search miss is a different report from a rating: it names a gap in the
// catalog rather than scoring an experience, so it carries no rating and
// must not land in the same number.
const searchMiss = normalizeComment(args["search-miss"]);
if (searchMiss) {
if (!shouldTrack()) {
console.log(c.dim("Telemetry is disabled. Nothing sent."));
return;
}
const wanted = normalizeComment(args.wanted);
const tier = normalizeComment(args.tier);
trackCatalogSearchMiss({ query: searchMiss, wanted, tier });
// Ack before the forward, which is best-effort and bounded, so the
// reporter is never left waiting on it.
console.log(c.dim("Logged the gap. Thanks — that is how the catalog grows."));
await submitCatalogSearchMiss({ query: searchMiss, wanted, tier, cliVersion: VERSION });
return;
}
const comment = normalizeComment(args.comment);
const rating = reportRating(args.rating, comment, args["file-issue"] === true);
const source = parseFeedbackSource(args.source);
if (source === null) {
console.error(c.error('Source must be "person" or "agent"'));
failUsage();
}
if (!shouldTrack()) {
console.log(c.dim("Telemetry is disabled. Feedback not sent."));
return;
}
const doctorSummary = await getDoctorSummary();
// Join keys tying this report to the install's PostHog rows — see
// buildTelemetryJoinKeys. Appended to the env string so they surface in
// the forwarded report; mirrored as structured props on the PostHog event.
const feedbackId = randomUUID();
const config = readConfig();
const joinKeys = buildTelemetryJoinKeys({
feedbackId,
anonymousId: config.anonymousId,
recentRenders: config.recentRenders,
lastCheck: config.lastCheck,
});
const envWithJoinKeys = doctorSummary ? `${doctorSummary} ${joinKeys}` : joinKeys;
trackFeedback({
rating,
comment,
doctorSummary,
feedbackId,
recentRenderIds: config.recentRenders?.map((r) => r.id),
});
// Ack first so the user isn't kept waiting on the best-effort forward (which
// is bounded to a few seconds and never surfaces an error either way).
console.log(c.dim("Thanks for the feedback!"));
await submitFeedback({
rating,
comment,
cliVersion: VERSION,
env: envWithJoinKeys,
source,
email: feedbackEmail(),
});
if (args["file-issue"] === true && rating !== undefined) {
await fileGithubIssue({
rating,
comment,
rawDir: args.dir,
yes: args.yes === true,
includeOutsideFiles: args["include-outside-files"] === true,
doctorSummary,
});
}
},
});