diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 182f0f0a56..be8e6eb376 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -2673,6 +2673,17 @@ first to see which media would upload and the compressed size, without authenticating, uploading, or starting anything. If you are over, add only paths you have verified are unneeded to `.hyperframesignore`. +A file outside the project folder that a composition points at is copied into +the zip, unless it sits in a private location (env files, Git data, hidden, +system and app-data folders) or is reached from a file that came in with an +imported project: then it is left out, with a warning naming it. Under +`--json`, the result lists those as `left_out`, each with the `file` that points +at it, the `reference` as written, its `path` from the project folder, the +`reason` (`blocklisted` or `received`) and `levels_up`, how many folders above +the project it is. A full run also prints each as a `{"event":"left_out",…}` +line on stderr, so a wrapper can ask with `--dry-run --json` before uploading +and still hear about each one during the run. + Render parameters mirror local `hyperframes render` where they overlap: | Flag | Default | Description | diff --git a/packages/cli/src/commands/cloud/render.leftOut.test.ts b/packages/cli/src/commands/cloud/render.leftOut.test.ts new file mode 100644 index 0000000000..3438af2c29 --- /dev/null +++ b/packages/cli/src/commands/cloud/render.leftOut.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it, onTestFinished } from "vitest"; +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; + +const cliEntry = resolve(fileURLToPath(import.meta.url), "..", "..", "..", "cli.ts"); + +/** `/p` whose received index.html points at `/notes.txt` and whose own page points at `/.env`. */ +function importedProject(): string { + const root = mkdtempSync(join(tmpdir(), "hf-cloud-left-out-")); + onTestFinished(() => rmSync(root, { recursive: true, force: true })); + const dir = join(root, "p"); + mkdirSync(join(dir, ".hyperframes"), { recursive: true }); + writeFileSync(join(root, "notes.txt"), "outside"); + writeFileSync(join(root, ".env"), "SECRET=1"); + writeFileSync( + join(dir, "index.html"), + `
`, + ); + writeFileSync(join(dir, "mine.html"), ``); + writeFileSync( + join(dir, ".hyperframes", "received-files.json"), + JSON.stringify({ files: ["index.html"] }), + ); + return dir; +} + +describe("cloud render --dry-run --json lists what the upload leaves out", () => { + it("in its result, and as a left_out event per file on stderr", () => { + const dir = importedProject(); + const result = spawnSync( + "bun", + ["run", cliEntry, "cloud", "render", dir, "--dry-run", "--json"], + { + encoding: "utf-8", + timeout: 30_000, + env: { + ...process.env, + CI: "1", + HEYGEN_API_URL: "http://127.0.0.1:1", + HYPERFRAMES_NO_UPDATE_CHECK: "1", + HYPERFRAMES_NO_TELEMETRY: "1", + HOME: dir, + }, + }, + ); + + expect(result.status).toBe(0); + const { archive } = JSON.parse(result.stdout) as { archive: { left_out: unknown[] } }; + const expected = [ + { + file: "index.html", + reference: "../notes.txt", + path: "../notes.txt", + reason: "received", + levels_up: 1, + }, + { + file: "mine.html", + reference: "../.env", + path: "../.env", + reason: "blocklisted", + levels_up: 1, + }, + ]; + expect(archive.left_out).toHaveLength(2); + expect(archive.left_out).toEqual(expect.arrayContaining(expected)); + const events = result.stderr + .split("\n") + .filter((line) => line.startsWith('{"event":"left_out"')) + .map((line) => JSON.parse(line) as Record); + expect(events).toEqual( + archive.left_out.map((entry) => ({ event: "left_out", ...(entry as object) })), + ); + // The person's warning is still printed beside each event. + expect(result.stderr).toContain("mine.html references ../.env, which is outside the project"); + }); +}); diff --git a/packages/cli/src/commands/cloud/render.ts b/packages/cli/src/commands/cloud/render.ts index dc15fb027e..c072d54db2 100644 --- a/packages/cli/src/commands/cloud/render.ts +++ b/packages/cli/src/commands/cloud/render.ts @@ -63,6 +63,8 @@ import { validateVariablesAgainstProject, } from "../../utils/variables.js"; import { withMeta } from "../../utils/updateCheck.js"; +import type { LeftOutReference, OnLeftOut } from "../../utils/leftOutReference.js"; +import { trackUploadLeftOut } from "../../telemetry/uploadLeftOut.js"; import type { Example } from "../_examples.js"; import { @@ -338,6 +340,7 @@ export default defineCommand({ withMeta({ render: { render_id: renderId, status: "queued" as const }, swapped_fonts: preparedArchive?.swappedFonts ?? [], + left_out: preparedArchive?.leftOut ?? [], }), null, 2, @@ -384,6 +387,7 @@ export default defineCommand({ output_path: outputPath, bytes_written: downloadResult.bytes, swapped_fonts: preparedArchive?.swappedFonts ?? [], + left_out: preparedArchive?.leftOut ?? [], }), null, 2, @@ -664,6 +668,7 @@ interface PreparedLocalArchive { largestFiles: ArchiveFileSummary[]; offloaded: OffloadedMedia[]; swappedFonts: string[]; + leftOut: LeftOutReference[]; } function summarizeLargestFiles(fileMap: Map): ArchiveFileSummary[] { @@ -685,9 +690,13 @@ async function prepareLocalArchive( console.log(""); console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`); } - const { fileMap, entryPath } = stageProjectFiles(project, composition, (warning) => - (asJson ? console.error : console.log)(c.warn(` ${warning}`)), + const leftOut: LeftOutReference[] = []; + const { fileMap, entryPath } = stageProjectFiles( + project, + composition, + warnAndListLeftOut(leftOut, asJson), ); + trackUploadLeftOut("cloud_render", leftOut, !upload); const swappedFonts = await embedSystemFonts({ dir: project.dir, entryFile: composition, @@ -718,6 +727,7 @@ async function prepareLocalArchive( largestFiles, offloaded, swappedFonts, + leftOut, }; if (upload) assertArchiveFits(sizeBytes, largestFiles); if (!asJson && sizeBytes >= ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) { @@ -726,10 +736,19 @@ async function prepareLocalArchive( return prepared; } +function warnAndListLeftOut(leftOut: LeftOutReference[], asJson: boolean): OnLeftOut { + return (warning, reference) => { + leftOut.push(reference); + if (!asJson) return console.log(c.warn(` ${warning}`)); + console.error(c.warn(` ${warning}`)); + console.error(JSON.stringify({ event: "left_out", ...reference })); + }; +} + function stageProjectFiles( project: ProjectDir, composition: string | undefined, - onLeftOut: (warning: string) => void, + onLeftOut: OnLeftOut, ): { fileMap: Map; entryPath: string } { try { const fileMap = stagePublishFiles(project.dir, OFFLOAD_MIN_BYTES, onLeftOut); @@ -874,6 +893,7 @@ function reportDryRun(prepared: PreparedLocalArchive, asJson: boolean): void { largest_files: prepared.largestFiles, offloaded_media: prepared.offloaded, swapped_fonts: prepared.swappedFonts, + left_out: prepared.leftOut, }, }), null, diff --git a/packages/cli/src/commands/feedback.ts b/packages/cli/src/commands/feedback.ts index 48b1ad05df..af594ebc80 100644 --- a/packages/cli/src/commands/feedback.ts +++ b/packages/cli/src/commands/feedback.ts @@ -22,6 +22,8 @@ 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 } from "../utils/leftOutReference.js"; +import { trackUploadLeftOut } from "../telemetry/uploadLeftOut.js"; export const examples: Example[] = [ ["Submit render feedback", 'hyperframes feedback --rating 8 --comment "fast but font missing"'], @@ -121,7 +123,12 @@ async function publishRepro(dir: string): Promise { spinner.start("Publishing minimal repro..."); try { const leftOut: string[] = []; - const archive = createPublishArchive(dir, (warning) => leftOut.push(warning)); + const references: LeftOutReference[] = []; + const archive = createPublishArchive(dir, (warning, reference) => { + leftOut.push(warning); + references.push(reference); + }); + trackUploadLeftOut("feedback", references); const published = await publishProjectArchive(dir, { archive }); spinner.stop(c.success("Repro published")); for (const warning of leftOut) clack.log.warn(c.warn(warning)); diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts index 14415efb38..26da707f0b 100644 --- a/packages/cli/src/commands/publish.ts +++ b/packages/cli/src/commands/publish.ts @@ -31,6 +31,8 @@ import { writeTeamProject, } from "../utils/projectLink.js"; import { cliSourced } from "../utils/sourceTag.js"; +import type { LeftOutReference } from "../utils/leftOutReference.js"; +import { trackUploadLeftOut } from "../telemetry/uploadLeftOut.js"; export const examples: Example[] = [ ["Publish the current project privately to a stable URL", "hyperframes publish"], @@ -234,7 +236,12 @@ export default defineCommand({ const proxyFlagValue = typeof args.proxy === "boolean" ? args.proxy : undefined; const autoProxy = resolveAutoProxy(dir, proxyFlagValue); const leftOut: string[] = []; - const fileMap = buildPublishFileMap(dir, (warning) => leftOut.push(warning)); + const references: LeftOutReference[] = []; + const fileMap = buildPublishFileMap(dir, (warning, reference) => { + leftOut.push(warning); + references.push(reference); + }); + trackUploadLeftOut("publish", references); let proxyBakeManifest: Awaited> | undefined; if (autoProxy) { proxyBakeManifest = await bakeMediaProxies(dir, fileMap); diff --git a/packages/cli/src/telemetry/uploadLeftOut.test.ts b/packages/cli/src/telemetry/uploadLeftOut.test.ts new file mode 100644 index 0000000000..c99728a75a --- /dev/null +++ b/packages/cli/src/telemetry/uploadLeftOut.test.ts @@ -0,0 +1,44 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { LeftOutReference } from "../utils/leftOutReference.js"; + +const trackEvent = vi.fn(); +vi.mock("./client.js", () => ({ trackEvent: (...args: unknown[]) => trackEvent(...args) })); + +const { trackUploadLeftOut } = await import("./uploadLeftOut.js"); + +const at = (levels_up: number | null, reason: LeftOutReference["reason"] = "received") => ({ + file: "index.html", + reference: "../secret/name.png", + path: "../secret/name.png", + reason, + levels_up, +}); + +describe("cli_upload_left_out", () => { + beforeEach(() => trackEvent.mockClear()); + + it("counts what was left out and how far above the project, and names nothing", () => { + trackUploadLeftOut("cloud_render", [at(1), at(1, "blocklisted"), at(2), at(5), at(null)], true); + expect(trackEvent).toHaveBeenCalledTimes(1); + const [event, properties] = trackEvent.mock.calls[0]!; + expect(event).toBe("cli_upload_left_out"); + expect(properties).toEqual({ + command: "cloud_render", + dry_run: true, + left_out_count: 5, + received_count: 4, + blocklisted_count: 1, + max_levels_up: 5, + levels_up_1: 2, + levels_up_2: 1, + levels_up_3_plus: 1, + other_drive: 1, + }); + expect(JSON.stringify(properties)).not.toMatch(/secret|name\.png|index\.html/); + }); + + it("sends nothing for an upload that left nothing out", () => { + trackUploadLeftOut("publish", []); + expect(trackEvent).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/cli/src/telemetry/uploadLeftOut.ts b/packages/cli/src/telemetry/uploadLeftOut.ts new file mode 100644 index 0000000000..510329dc11 --- /dev/null +++ b/packages/cli/src/telemetry/uploadLeftOut.ts @@ -0,0 +1,30 @@ +import type { LeftOutReference } from "../utils/leftOutReference.js"; +import { trackEvent } from "./client.js"; + +export type LeftOutCommand = "publish" | "cloud_render" | "feedback"; + +/** What an upload left out, as counts and folder depths: never a name or a path. */ +function leftOutCounts(references: readonly LeftOutReference[]) { + const levels = references.map((reference) => reference.levels_up); + const counted = (keep: (levels: number | null) => boolean) => levels.filter(keep).length; + return { + left_out_count: references.length, + received_count: references.filter((reference) => reference.reason === "received").length, + blocklisted_count: references.filter((reference) => reference.reason === "blocklisted").length, + max_levels_up: Math.max(0, ...levels.map((n) => n ?? 0)), + levels_up_1: counted((n) => n === 1), + levels_up_2: counted((n) => n === 2), + levels_up_3_plus: counted((n) => n !== null && n >= 3), + other_drive: counted((n) => n === null), + }; +} + +/** Sent once per upload that left something out; `dryRun` marks a `cloud render --dry-run` that uploaded nothing. */ +export function trackUploadLeftOut( + command: LeftOutCommand, + references: readonly LeftOutReference[], + dryRun = false, +): void { + if (references.length === 0) return; + trackEvent("cli_upload_left_out", { command, dry_run: dryRun, ...leftOutCounts(references) }); +} diff --git a/packages/cli/src/utils/leftOutReference.test.ts b/packages/cli/src/utils/leftOutReference.test.ts new file mode 100644 index 0000000000..b23aa34f45 --- /dev/null +++ b/packages/cli/src/utils/leftOutReference.test.ts @@ -0,0 +1,90 @@ +import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { stagePublishFiles } from "./publishProject.js"; +import type { LeftOutReference } from "./leftOutReference.js"; + +const dirs: string[] = []; +afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true }))); + +/** Stages `/` from `files` (`` in a body is the root's path) and hears what it leaves out. */ +function leftOutOf(project: string, files: Record, received?: string[]) { + const root = mkdtempSync(join(tmpdir(), "hf-left-out-")); + dirs.push(root); + for (const [name, body] of Object.entries(files)) { + mkdirSync(dirname(join(root, name)), { recursive: true }); + writeFileSync(join(root, name), body.replaceAll("", root)); + } + if (received) { + mkdirSync(join(root, project, ".hyperframes"), { recursive: true }); + writeFileSync( + join(root, project, ".hyperframes", "received-files.json"), + JSON.stringify({ files: received }), + ); + } + const heard: { warning: string; reference: LeftOutReference }[] = []; + stagePublishFiles(join(root, project), Infinity, (warning, reference) => + heard.push({ warning, reference }), + ); + return { root, heard }; +} + +describe("each file an upload leaves out is also reported for a program", () => { + it("names the referring file, the reference as written, where it leads and how far up", () => { + const { heard } = leftOutOf("work/p", { + ".ssh/id_ed25519": "KEY", + "work/p/index.html": ``, + }); + expect(heard).toEqual([ + { + warning: expect.stringContaining("index.html references ../../.ssh/id_ed25519"), + reference: { + file: "index.html", + reference: "../../.ssh/id_ed25519", + path: "../../.ssh/id_ed25519", + reason: "blocklisted", + levels_up: 2, + }, + }, + ]); + }); + + it("gives an absolute reference its path from the project, and a received one its reason", () => { + const { heard } = leftOutOf( + "p", + { "shared/logo.png": "png", "p/index.html": `` }, + ["index.html"], + ); + expect(heard.map(({ reference }) => reference)).toEqual([ + { + file: "index.html", + reference: expect.stringMatching(/\/shared\/logo\.png$/), + path: "../shared/logo.png", + reason: "received", + levels_up: 1, + }, + ]); + }); + + it.skipIf(process.platform === "win32")("reports a link by its own path and its target", () => { + const root = mkdtempSync(join(tmpdir(), "hf-left-out-link-")); + dirs.push(root); + mkdirSync(join(root, ".config")); + writeFileSync(join(root, ".config", "token"), "KEY"); + mkdirSync(join(root, "p")); + writeFileSync(join(root, "p", "index.html"), ""); + symlinkSync(join(root, ".config", "token"), join(root, "p", "token.txt")); + const heard: LeftOutReference[] = []; + stagePublishFiles(join(root, "p"), Infinity, (_warning, reference) => heard.push(reference)); + expect(heard).toEqual([ + { + file: "token.txt", + reference: "token.txt", + path: "../.config/token", + reason: "blocklisted", + levels_up: 1, + }, + ]); + }); +}); diff --git a/packages/cli/src/utils/leftOutReference.ts b/packages/cli/src/utils/leftOutReference.ts new file mode 100644 index 0000000000..f2769251fa --- /dev/null +++ b/packages/cli/src/utils/leftOutReference.ts @@ -0,0 +1,28 @@ +import { isAbsolute, relative } from "node:path"; +import { realFilePath } from "@hyperframes/studio-server/safe-path"; + +/** `blocklisted`: a private location; `received`: reached from a file that came in with an imported project. */ +export type LeftOutReason = "blocklisted" | "received"; + +/** One file an upload left out. `path` is from the project folder; `levels_up` is null on another drive. */ +export interface LeftOutReference { + file: string; + reference: string; + path: string; + reason: LeftOutReason; + levels_up: number | null; +} + +export type OnLeftOut = (warning: string, reference: LeftOutReference) => void; + +export function leftOutReference( + projectDir: string, + file: string, + reference: string, + absPath: string, + reason: LeftOutReason, +): LeftOutReference { + const path = relative(realFilePath(projectDir), realFilePath(absPath)).replaceAll("\\", "/"); + const levels_up = isAbsolute(path) ? null : path.split("/").filter((s) => s === "..").length; + return { file, reference, path, reason, levels_up }; +} diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts index f20f13a038..05c90c3282 100644 --- a/packages/cli/src/utils/publishProject.ts +++ b/packages/cli/src/utils/publishProject.ts @@ -29,6 +29,7 @@ import { linksToPrivateOutsideFile, receivedFiles, } from "./privateProjectFile.js"; +import { leftOutReference, type OnLeftOut } from "./leftOutReference.js"; const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]); const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]); @@ -398,7 +399,7 @@ interface ExternalAssetContext { externalMap: Map; usedArchivePaths: Set; leftOut: Set; - onLeftOut?: (warning: string) => void; + onLeftOut?: OnLeftOut; received: (path: string) => boolean; } @@ -448,7 +449,7 @@ function includeReferencedProjectFile( if (staysOut(ctx, rel, absPath)) return; if (!existsSync(absPath)) continue; if (ctx.received(entryPath) && linksOutside(ctx.absProjectDir, absPath)) { - return leaveOut(ctx, entryPath, rawPath, RECEIVED); + return leaveOut(ctx, entryPath, rawPath, absPath, RECEIVED); } if (statSync(absPath).isFile()) { ctx.fileContents.set(rel, stageFile(absPath, ctx.onDiskMinBytes)); @@ -472,12 +473,17 @@ function leaveOut( ctx: ExternalAssetContext, entryPath: string, rawPath: string, + absPath: string, why = PRIVATE, ): void { const warning = `${entryPath} references ${rawPath}, ${why}; it was left out of the upload.`; if (ctx.leftOut.has(warning)) return; ctx.leftOut.add(warning); - ctx.onLeftOut?.(warning); + const reason = why === RECEIVED ? "received" : "blocklisted"; + ctx.onLeftOut?.( + warning, + leftOutReference(ctx.absProjectDir, entryPath, rawPath, absPath, reason), + ); } function archiveTargetOf( @@ -493,11 +499,11 @@ function archiveTargetOf( try { if (!existsSync(absPath) || !statSync(absPath).isFile()) return undefined; if (ctx.received(options.entryPath)) { - leaveOut(ctx, options.entryPath, rawPath, RECEIVED); + leaveOut(ctx, options.entryPath, rawPath, absPath, RECEIVED); return undefined; } if (isPrivateOutsideFile(ctx.absProjectDir, absPath)) { - leaveOut(ctx, options.entryPath, rawPath); + leaveOut(ctx, options.entryPath, rawPath, absPath); return undefined; } } catch { @@ -689,7 +695,7 @@ export function localizeExternalAssets( absProjectDir: string, fileContents: Map, onDiskMinBytes = Infinity, - onLeftOut?: (warning: string) => void, + onLeftOut?: OnLeftOut, ): number { const ctx: ExternalAssetContext = { absProjectDir, @@ -723,7 +729,7 @@ export function localizeExternalAssets( */ export function buildPublishFileMap( projectDir: string, - onLeftOut?: (warning: string) => void, + onLeftOut?: OnLeftOut, ): Map { return stagePublishFiles(projectDir, Infinity, onLeftOut) as Map; } @@ -752,7 +758,7 @@ function composeNamesInText(fileContents: Map, filePaths: st export function stagePublishFiles( projectDir: string, onDiskMinBytes: number, - onLeftOut?: (warning: string) => void, + onLeftOut?: OnLeftOut, ): Map { const absProjectDir = resolve(projectDir); const filePaths: string[] = []; @@ -768,14 +774,17 @@ export function stagePublishFiles( const received = receivedFiles(absProjectDir); for (const filePath of filePaths) { const absPath = join(absProjectDir, filePath); - const why = linksToPrivateOutsideFile(absProjectDir, absPath) - ? "in a private location" + const reason = linksToPrivateOutsideFile(absProjectDir, absPath) + ? "blocklisted" : received(filePath) && linksOutside(absProjectDir, absPath) - ? "and came in with an imported project" + ? "received" : null; - if (why) { + if (reason) { + const why = + reason === "received" ? "and came in with an imported project" : "in a private location"; onLeftOut?.( `${filePath} links to a file outside the project ${why}; it was left out of the upload.`, + leftOutReference(absProjectDir, filePath, filePath, absPath, reason), ); continue; } @@ -839,7 +848,7 @@ export function zipPublishFileMap(fileContents: Map): PublishArc */ export function createPublishArchive( projectDir: string, - onLeftOut?: (warning: string) => void, + onLeftOut?: OnLeftOut, ): PublishArchiveResult { return zipPublishFileMap(buildPublishFileMap(projectDir, onLeftOut)); }