import { envProxyEnabled } from "@hyperframes/core/env-proxy"; import { basename, dirname, join, posix, relative, resolve } from "node:path"; import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync, type Stats, statSync, } from "node:fs"; import { parseHTML } from "linkedom"; import AdmZip from "adm-zip"; import ignore, { type Ignore } from "ignore"; import { CSS_URL_RE, isNonRelativeUrl, isPathInside, rewriteSrcsetUrls } from "@hyperframes/core"; import { decodeUrlPathVariants, encodeUrlPath } from "@hyperframes/parsers"; import { buildAuthHeaders } from "../auth/client.js"; import { tryResolveCredential } from "../auth/index.js"; import { isAuthError } from "../auth/errors.js"; import { envCredentialVar, isTokenExpired, type ResolvedCredential } from "../auth/resolver.js"; import { refreshIfNeeded } from "../cloud/auth.js"; import { writeProjectLink } from "./projectLink.js"; const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]); const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]); const HYPERFRAMES_IGNORE_FILE = ".hyperframesignore"; // Unanchored (no leading/mid slash) so it matches a dot-prefixed name at any // depth, same as the segments it replaces below — but as a matcher pattern // instead of a hard skip, a project's own `.hyperframesignore` negation can // still override it. const DEFAULT_PROJECT_IGNORE = ["/renders/", "/snapshots/", ".*"]; const PUBLISH_CONTENT_TYPE = "application/zip"; const PUBLISH_METADATA_TIMEOUT_MS = 30_000; const PUBLISH_UPLOAD_MIN_TIMEOUT_MS = 120_000; const PUBLISH_TRANSPORT_ATTEMPTS = 2; const PUBLISH_RETRY_DELAY_MS = 200; // Conservative floor — most connections are faster, but this prevents // premature aborts on slow/unstable networks (hotel wifi, tethering). const PUBLISH_UPLOAD_BYTES_PER_SECOND = 500_000; export interface PublishArchiveResult { buffer: Buffer; fileCount: number; } export interface PublishedProjectResponse { projectId: string; title: string; fileCount: number; url: string; claimToken: string; /** True when the project is owned by the authenticated publisher (created-and-owned or updated in place). */ claimed: boolean; } interface StagedUploadResponse { uploadUrl: string; uploadKey: string; contentType: string; uploadHeaders: Record; expiresInSeconds: number; } type JsonRecord = Record; function isRecord(value: unknown): value is JsonRecord { return typeof value === "object" && value !== null && !Array.isArray(value); } function dataRecord(payload: unknown): JsonRecord | null { if (!isRecord(payload) || !isRecord(payload["data"])) return null; return payload["data"]; } function stringField(record: JsonRecord, key: string): string | null { const value = record[key]; return typeof value === "string" ? value : null; } function parsePublishedProjectResponse(payload: unknown): PublishedProjectResponse | null { const data = dataRecord(payload); if (!data) return null; const projectId = stringField(data, "project_id"); const title = stringField(data, "title"); const url = stringField(data, "url"); const claimToken = stringField(data, "claim_token") ?? ""; const claimed = data["claimed"] === true; const fileCount = data["file_count"]; if (!projectId || !title || !url || typeof fileCount !== "number") { return null; } // Anonymous publishes must return a claim token; owned (claimed) ones need none. if (!claimed && !claimToken) { return null; } return { projectId, title, fileCount, url, claimToken, claimed, }; } function parseStagedUploadResponse( payload: unknown, archiveByteLength: number, ): StagedUploadResponse | null { const data = dataRecord(payload); if (!data) return null; const uploadUrl = stringField(data, "upload_url"); const uploadKey = stringField(data, "upload_key"); const contentType = stringField(data, "content_type") || PUBLISH_CONTENT_TYPE; if (!uploadUrl || !uploadKey) return null; const rawExpires = data["expires_in_seconds"]; const expiresInSeconds = typeof rawExpires === "number" && rawExpires > 0 ? rawExpires : 1800; return { uploadUrl, uploadKey, contentType, uploadHeaders: getUploadHeaders(data, uploadUrl, contentType, archiveByteLength), expiresInSeconds, }; } function getUploadHeaders( data: JsonRecord, uploadUrl: string, contentType: string, archiveByteLength: number, ): Record { const headers: Record = {}; const uploadHeaders = data["upload_headers"]; if (isRecord(uploadHeaders)) { for (const [key, value] of Object.entries(uploadHeaders)) { if (typeof value === "string" && key.trim()) { headers[key] = value; } } } setHeaderIfAbsent(headers, "content-type", contentType); const signedHeaders = new URL(uploadUrl).searchParams.get("X-Amz-SignedHeaders")?.split(";") ?? []; if (signedHeaders.includes("x-amz-server-side-encryption")) { setHeaderIfAbsent(headers, "x-amz-server-side-encryption", "AES256"); } if (signedHeaders.includes("content-length")) { setHeaderIfAbsent(headers, "content-length", String(archiveByteLength)); } return headers; } function setHeaderIfAbsent(headers: Record, name: string, value: string): void { if (!Object.keys(headers).some((key) => key.toLowerCase() === name)) headers[name] = value; } async function readJson(response: Response): Promise { return response .clone() .json() .catch(() => null); } class CredentialRejectedError extends Error {} async function metadataRequestError(response: Response, fallback: string): Promise { const message = await readErrorMessage(response, fallback); return response.status === 401 ? new CredentialRejectedError(message) : new Error(message); } const LOGIN_EXPIRED = "Your login expired. Run hyperframes auth login, then publish again."; const LOGIN_REQUIRED = "Publishing needs an account. Run hyperframes auth login to publish."; const LOGIN_CHANGED = "Your login changed during publish. Run publish again."; function rejectedCredentialMessage(credential: ResolvedCredential): string { const envVar = envCredentialVar(credential.source); return envVar ? `${envVar} was rejected. Fix or unset it, then publish again.` : LOGIN_EXPIRED; } /** Resolves the credential, or refreshes `checked` (a credential already resolved) without re-resolving. */ export async function resolvePublishCredential( checked?: ResolvedCredential | null, ): Promise { try { const credential = checked === undefined ? await tryResolveCredential() : checked; if (!credential) return null; // A checked login can expire during a long proxy bake; refresh it rather than fall back to an API key. const expired = credential.type === "oauth" && isTokenExpired(credential.expires_at, new Date()); if (expired && !credential.refresh_token) throw new Error(LOGIN_EXPIRED); return await refreshIfNeeded(expired ? { ...credential, refreshable: true } : credential); } catch (error) { if (isAuthError(error) && (error.code === "REFRESH_FAILED" || error.code === "LOGIN_EXPIRED")) { throw new Error(LOGIN_EXPIRED); } if (isAuthError(error) && error.code === "LOGIN_CHANGED") throw new Error(LOGIN_CHANGED); throw error; } } async function readErrorMessage(response: Response, fallback: string): Promise { const contentType = response.headers.get("content-type") || ""; if (contentType.includes("application/json")) { const payload = await readJson(response); if (isRecord(payload) && typeof payload["message"] === "string") { return payload["message"]; } } if (response.status === 403 && response.headers.get("cf-mitigated") === "challenge") { return "Publish upload was blocked before reaching HyperFrames. Please retry after staged uploads are available."; } const text = await response.text().catch(() => ""); return text.trim() ? `${fallback}: ${text.trim().slice(0, 180)}` : fallback; } function systemErrorMetadata(value: unknown): string[] { if (!isRecord(value)) return []; const metadata: string[] = []; if (typeof value["code"] === "string") metadata.push(value["code"]); if (typeof value["syscall"] === "string") metadata.push(`syscall=${value["syscall"]}`); if (typeof value["errno"] === "string" || typeof value["errno"] === "number") { metadata.push(`errno=${value["errno"]}`); } return metadata; } function redactUrlQuery(message: string): string { return message.replace(/(https?:\/\/[^\s?]+)\?[^\s]+/gu, "$1?[redacted]"); } function proxySupportHint(): string { const proxyConfigured = ["HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy"].some((key) => Boolean(process.env[key]?.trim()), ); if (!proxyConfigured || envProxyEnabled()) return ""; return ( ". Proxy variables are set but ignored by Node fetch; if this network requires them, retry with " + "NODE_USE_ENV_PROXY=1 (Node 22.21+)" ); } function describeFetchFailure(error: unknown): string { const message = error instanceof Error ? error.message : String(error); const cause = error instanceof Error ? error.cause : undefined; const causeMessage = cause instanceof Error ? cause.message : ""; const metadata = [...systemErrorMetadata(cause), ...systemErrorMetadata(error)].filter( (value, index, all) => all.indexOf(value) === index, ); const distinctCauseMessage = causeMessage && causeMessage !== message ? causeMessage : ""; const detail = [metadata.join(", "), distinctCauseMessage].filter(Boolean).join(": "); return `${redactUrlQuery(message)}${detail ? ` (${redactUrlQuery(detail)})` : ""}${proxySupportHint()}`; } function isRequestTimeout(error: unknown): boolean { return ( error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError") ); } function waitBeforePublishRetry(): Promise { return new Promise((resolve) => setTimeout(resolve, PUBLISH_RETRY_DELAY_MS)); } async function fetchForPublish( input: string, createInit: () => RequestInit, failureStage: string, attempts = 1, ): Promise { if (attempts < 1) throw new RangeError("Publish fetch attempts must be at least 1"); let lastError: unknown; let attemptsMade = 0; for (let attempt = 1; attempt <= attempts; attempt += 1) { attemptsMade = attempt; try { return await fetch(input, createInit()); } catch (error) { lastError = error; if (isRequestTimeout(error) || attempt === attempts) break; await waitBeforePublishRetry(); } } const attemptDetail = attemptsMade > 1 ? ` after ${attemptsMade} attempts` : ""; throw new Error(`${failureStage}${attemptDetail}: ${describeFetchFailure(lastError)}`, { cause: lastError instanceof Error ? lastError : undefined, }); } export function uploadTimeoutMs(byteLength: number): number { return Math.max( PUBLISH_UPLOAD_MIN_TIMEOUT_MS, Math.ceil((byteLength / PUBLISH_UPLOAD_BYTES_PER_SECOND) * 1000), ); } // Absolute, non-negotiable exclusions only — anything a `.hyperframesignore` // negation rule should be able to override (including dot-prefixed paths; // see DEFAULT_PROJECT_IGNORE) must go through the ignore matcher instead of // short-circuiting here. function shouldIgnoreSegment(segment: string): boolean { return IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment); } function createProjectIgnore(rootDir: string): Ignore { const matcher = ignore().add(DEFAULT_PROJECT_IGNORE); const ignorePath = join(rootDir, HYPERFRAMES_IGNORE_FILE); if (existsSync(ignorePath)) { matcher.add(readFileSync(ignorePath, "utf-8")); } return matcher; } function collectProjectFiles( rootDir: string, currentDir: string, paths: string[], matcher: Ignore, ): void { for (const entry of readdirSync(currentDir, { withFileTypes: true })) { if (shouldIgnoreSegment(entry.name)) continue; const absolutePath = join(currentDir, entry.name); const relativePath = relative(rootDir, absolutePath).replaceAll("\\", "/"); if (!relativePath) continue; if (entry.isDirectory()) { if (matcher.ignores(`${relativePath}/`)) continue; collectProjectFiles(rootDir, absolutePath, paths, matcher); continue; } if (!statSync(absolutePath).isFile()) continue; if (matcher.ignores(relativePath)) continue; paths.push(relativePath); } } const EXT_ASSETS_PREFIX = "_ext"; /** Files whose text a reference rewrite or scan reads; they are always staged in memory. */ export const TEXT_FILE_EXTS = /\.(html?|css|m?js|cjs|json|svg|xml|txt)$/i; /** A large non-text project file left on disk; `size` and `mtimeMs` detect an edit after staging. */ export interface DiskFile { absPath: string; size: number; mtimeMs: number; } export type StagedFile = Buffer | DiskFile; export function stagedSize(file: StagedFile): number { return Buffer.isBuffer(file) ? file.byteLength : file.size; } function assertSame(file: DiskFile, now: Stats | undefined): void { if (now?.size !== file.size || now.mtimeMs !== file.mtimeMs) { throw new Error(`${file.absPath} changed on disk while it was being prepared. Run it again.`); } } export function assertUnchanged(file: DiskFile): void { assertSame(file, statSync(file.absPath, { throwIfNoEntry: false })); } /** Reads through one descriptor, so `check` (run before and after) sees the stat of the bytes returned. */ export function readChecked(path: string, check: (stat: Stats) => void): Buffer { const fd = openSync(path, "r"); try { check(fstatSync(fd)); const bytes = readFileSync(fd); check(fstatSync(fd)); return bytes; } finally { closeSync(fd); } } /** The staged bytes; a file left on disk is read now and must not have changed since staging. */ export function readStaged(file: StagedFile): Buffer { if (Buffer.isBuffer(file)) return file; return readChecked(file.absPath, (stat) => assertSame(file, stat)); } function stageFile(absPath: string, onDiskMinBytes: number): StagedFile { const fd = openSync(absPath, "r"); try { const { size, mtimeMs } = fstatSync(fd); if (size < onDiskMinBytes || TEXT_FILE_EXTS.test(absPath)) return readFileSync(fd); return { absPath, size, mtimeMs }; } finally { closeSync(fd); } } interface ExternalAssetContext { absProjectDir: string; fileContents: Map; onDiskMinBytes: number; externalMap: Map; usedArchivePaths: Set; } function addExternalAsset(ctx: ExternalAssetContext, absPath: string): string { const existing = ctx.externalMap.get(absPath); if (existing) return existing; const rel = relative(ctx.absProjectDir, absPath).replaceAll("\\", "/"); const stripped = rel.replace(/^(?:\.\.\/)+/, ""); let archivePath = `${EXT_ASSETS_PREFIX}/${stripped}`; if (ctx.usedArchivePaths.has(archivePath)) { const ext = posix.extname(archivePath); const base = archivePath.slice(0, archivePath.length - ext.length); let i = 2; while (ctx.usedArchivePaths.has(`${base}_${i}${ext}`)) i++; archivePath = `${base}_${i}${ext}`; } ctx.fileContents.set(archivePath, stageFile(absPath, ctx.onDiskMinBytes)); ctx.externalMap.set(absPath, archivePath); ctx.usedArchivePaths.add(archivePath); return archivePath; } function tryResolveExternal( ctx: ExternalAssetContext, rawPath: string, referrerAbsDir: string, ): string | null { if (isNonRelativeUrl(rawPath)) return null; for (const path of decodeUrlPathVariants(rawPath)) { const absPath = resolve(referrerAbsDir, path); if (isPathInside(absPath, ctx.absProjectDir)) return null; try { if (!existsSync(absPath) || !statSync(absPath).isFile()) continue; } catch { continue; } return encodeUrlPath(addExternalAsset(ctx, absPath)); } return null; } /** Resolves a raw attribute or CSS `url()` value to the archive path or absolute * URL it should point at, or `null` to leave it untouched. */ export type HtmlAttributeResolver = (rawValue: string, referrerAbsDir: string) => string | null; function referenceFrom(entryPath: string, target: string): string { return isNonRelativeUrl(target) ? target : posix.relative(posix.dirname(entryPath), target); } export function rewriteCssUrls( css: string, referrerAbsDir: string, entryPath: string, resolveTarget: HtmlAttributeResolver, ): { css: string; modified: boolean } { let modified = false; const rewritten = css.replace(CSS_URL_RE, (full, quote: string, rawUrl: string) => { const target = resolveTarget((rawUrl || "").trim(), referrerAbsDir); if (!target) return full; modified = true; return `url(${quote || ""}${referenceFrom(entryPath, target)}${quote || ""})`; }); return { css: rewritten, modified }; } interface RewriteHtmlAttributesOptions { /** Attributes to inspect (default: src + href, matching the external-asset * localization use case below). */ attrs?: string[]; /** CSS selector narrowing which elements are inspected (default: derived * from `attrs`, e.g. `"[src], [href]"`). Callers that only care about one * tag (e.g. `