Skip to content

Write HTML. Render video. Built for agents.

5.2 KB
Raw Blame
import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
import { readdirSync, type Dirent } from "node:fs";
import { realpath, resolveWithinProject as resolveInProject } from "@hyperframes/core/safe-path";
import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
import { STUDIO_MANUAL_EDITS_PATH } from "./manualEditsRenderScript.js";
import { STUDIO_MOTION_PATH } from "./studioMotionRenderScript.js";

// `isSafePath` lives at the package root so non-studio-api layers (compiler,
// CLI, engine) can share it without a backwards dependency on studio-api.
// Re-exported here for back-compat with existing `../helpers/safePath.js` imports.
export {
  folderGone,
  isProjectRootMissing,
  isSafePath,
  mkdirWithinProject,
  realpath,
  realProjectRoot,
} from "@hyperframes/core/safe-path";

/** Core's `resolveWithinProject`, closed to the desktop app's private files for every route a request path reaches. */
export function resolveWithinProject(base: string, relativePath: string): string | null {
  const resolved = resolveInProject(base, relativePath);
  return resolved && !isPrivateProjectFile(base, resolved) ? resolved : null;
}

/** The real path; for a path not there (yet, or any more), the nearest existing folder's real path plus the rest. */
export function realFilePath(filePath: string): string {
  try {
    return realpath(filePath);
  } catch {
    const dir = dirname(filePath);
    return dir === filePath ? filePath : join(realFilePath(dir), basename(filePath));
  }
}

// `.hyperframes/` holds the desktop app's and the CLI's own records (a hand-off, chat history, read marks): no route
// reaches any of it, the folder itself included, but Studio's own files and the app's request pictures.
const STUDIO_FILES = new Set([STUDIO_MOTION_PATH, STUDIO_MANUAL_EDITS_PATH]);
const STUDIO_FOLDERS = [".hyperframes/prepared-assets", ".hyperframes/requests"];

/** For a project-relative path with `/` separators. */
export function isPrivateProjectPath(relPath: string): boolean {
  const path = relPath.toLowerCase();
  return (
    (path === ".hyperframes" || path.startsWith(".hyperframes/")) &&
    !STUDIO_FILES.has(path) &&
    !STUDIO_FOLDERS.some((folder) => path === folder || path.startsWith(`${folder}/`))
  );
}

export function isPrivateProjectFile(projectDir: string, filePath: string): boolean {
  const rel = (from: string, to: string) => relative(from, to).split(sep).join("/");
  return [rel(projectDir, filePath), rel(realFilePath(projectDir), realFilePath(filePath))].some(
    isPrivateProjectPath,
  );
}

/**
 * `resolveWithinProject` with every link inside the project resolved now, so a write to the result lands on the
 * file checked here even if a link on the way is retargeted before the write.
 */
export function pinWithinProject(base: string, relativePath: string): string | null {
  return pinResolved(base, resolveWithinProject(base, relativePath));
}

/** `pinWithinProject` for the app's and the CLI's own records under `.hyperframes/`, which no route serves. */
export function pinProjectRecord(base: string, relativePath: string): string | null {
  return pinResolved(base, resolveInProject(base, relativePath));
}

function pinResolved(base: string, checked: string | null): string | null {
  if (!checked) return null;
  const inside = relative(realFilePath(base), realFilePath(checked));
  const escapes = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
  return escapes ? null : join(base, inside);
}

const IGNORE_DIRS = new Set([
  ".thumbnails",
  ".transcode-cache",
  ".waveform-cache",
  "node_modules",
  ".git",
]);

function shouldIgnoreDir(rel: string): boolean {
  return rel === ".hyperframes/backup";
}

/**
 * True when any directory segment of a relative path is a dot-directory or
 * node_modules. Projects that vendor tooling assets under dot-directories
 * (.hyperframes/, .cache/, …) ship example/preset HTML that must not surface
 * as project compositions or studio lint targets (#1384). The file tree is
 * deliberately not filtered — this only gates discovery.
 */
export function isInHiddenOrVendorDir(relPath: string): boolean {
  const segments = relPath.split("/");
  return segments.slice(0, -1).some((seg) => seg.startsWith(".") || seg === "node_modules");
}

const UNREADABLE_DIR_CODES = new Set(["EACCES", "EPERM", "ENOENT", "ENOTDIR"]);

/** Recursively walk a directory and return relative file paths. A subfolder that is unreadable
 * or removed mid-walk is skipped; any other failure, or an unreadable `dir` itself, throws. */
export function walkDir(dir: string, prefix = ""): string[] {
  let entries: Dirent[];
  try {
    entries = readdirSync(dir, { withFileTypes: true });
  } catch (err) {
    const code = (err as NodeJS.ErrnoException).code;
    if (!prefix || !code || !UNREADABLE_DIR_CODES.has(code)) throw err;
    return [];
  }
  const files: string[] = [];
  for (const entry of entries) {
    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
    if (IGNORE_DIRS.has(entry.name) || RENDER_TEMP_DIR.test(entry.name) || shouldIgnoreDir(rel))
      continue;
    if (entry.isDirectory()) {
      files.push(...walkDir(join(dir, entry.name), rel));
    } else {
      files.push(rel);
    }
  }
  return files;
}