Skip to content

Write HTML. Render video. Built for agents.

9.4 KB
Raw Blame
import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { isAbsolute, join, relative, resolve } from "node:path";
import { defineCommand } from "citty";
import {
  EXTRACT_CACHE_MIN_AGE_MS,
  directorySizeBytes,
  gcExtractionCache,
  resolveExtractCacheDir,
} from "@hyperframes/engine";
import {
  DEFAULT_HISTORY_ROOT,
  PROXY_CACHE_DIR_NAME,
  cleanupProxyCache,
  listProjectHistories,
  pruneGoneProjectHistories,
} from "@hyperframes/studio-server";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
import { formatBytes } from "../ui/format.js";
import { setCommandExitCode } from "../utils/commandResult.js";
import { loadProducer } from "../utils/producer.js";
import { redactHome } from "./doctor.js";
import { withMeta } from "../utils/updateCheck.js";

export const examples: Example[] = [
  ["See what HyperFrames left on disk, remove nothing", "hyperframes clean --dry-run"],
  ["Remove it", "hyperframes clean"],
  ["Also remove snapshots and saved check reports", "hyperframes clean --snapshots"],
  ["For agents", "hyperframes clean --json"],
];

/** A render dir with no owner record (made before owners were recorded) counts as abandoned after this long idle. */
const OWNERLESS_IDLE_MS = 6 * 60 * 60 * 1000;
/** A video proxy nobody has used for this long is regenerable; a Studio still using one keeps touching it. */
const PROXY_IDLE_MS = 60 * 60 * 1000;

export interface Leftover {
  what: string;
  path: string;
  bytes: number;
}

export interface CleanOptions {
  projectDir: string;
  dryRun: boolean;
  snapshots: boolean;
  /** Where to look; each defaults to the real location (tests point them at scratch dirs). */
  historyRoot?: string;
  tempDir?: string;
  debugDir?: string;
}

export interface CleanResult {
  removed: Leftover[];
  alsoReclaimable: Leftover[];
  errors: string[];
}

interface Sweep {
  dryRun: boolean;
  result: CleanResult;
}

function recordError(sweep: Sweep, error: unknown): void {
  sweep.result.errors.push(error instanceof Error ? error.message : String(error));
}

/** Runs one kind of sweep; a failure is reported and the rest of the clean goes on. */
async function attempt(sweep: Sweep, step: () => unknown): Promise<void> {
  try {
    await step();
  } catch (error) {
    recordError(sweep, error);
  }
}

/** A HyperFrames project: its index.html holds a composition root, not just any website. */
function isProject(dir: string): boolean {
  try {
    return readFileSync(join(dir, "index.html"), "utf-8").includes("data-composition-id");
  } catch {
    return false;
  }
}

function realDir(dir: string): string {
  try {
    return realpathSync(dir);
  } catch {
    return resolve(dir);
  }
}

function knownProjectDirs(sweep: Sweep, historyRoot: string): string[] {
  try {
    return listProjectHistories(historyRoot).map((record) => record.projectDir);
  } catch (error) {
    recordError(sweep, error);
    return [];
  }
}

function drop(sweep: Sweep, what: string, path: string): void {
  const bytes = directorySizeBytes(path);
  try {
    if (!sweep.dryRun)
      rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
    sweep.result.removed.push({ what, path, bytes });
  } catch (error) {
    recordError(sweep, error);
  }
}

function sweepProxies(sweep: Sweep, project: string): void {
  const proxies = join(project, PROXY_CACHE_DIR_NAME);
  const swept = cleanupProxyCache(proxies, {
    maxBytes: Number.POSITIVE_INFINITY,
    maxIdleMs: PROXY_IDLE_MS,
    minSweepIntervalMs: 0,
    dryRun: sweep.dryRun,
  });
  if (swept.removed.length === 0) return;
  sweep.result.removed.push({
    what: "Video proxies",
    path: proxies,
    bytes: swept.bytesBefore - swept.bytesAfter,
  });
}

const SNAPSHOT_FOLDERS = [
  { what: "Snapshots", path: ["snapshots"] },
  { what: "Snapshots", path: [".hyperframes", "artifacts", "snapshots"] },
  { what: "Check reports", path: [".hyperframes", "artifacts", "checks"] },
];

function staysUnderArtifacts(project: string, path: string, folder: readonly string[]): boolean {
  try {
    const allowed = join(realpathSync(project), ...folder);
    const target = realpathSync(path);
    const fromAllowed = relative(allowed, target);
    return fromAllowed === "" || (!fromAllowed.startsWith("..") && !isAbsolute(fromAllowed));
  } catch {
    return false;
  }
}

function sweepSnapshots(sweep: Sweep, project: string, remove: boolean): void {
  for (const folder of SNAPSHOT_FOLDERS) {
    const path = join(project, ...folder.path);
    if (!existsSync(path) || !staysUnderArtifacts(project, path, folder.path)) continue;
    if (remove) drop(sweep, folder.what, path);
    else
      sweep.result.alsoReclaimable.push({
        what: folder.what,
        path,
        bytes: directorySizeBytes(path),
      });
  }
}

async function sweepHistories(sweep: Sweep, historyRoot: string, tempDir: string): Promise<void> {
  const pruned = await pruneGoneProjectHistories(historyRoot, {
    dryRun: sweep.dryRun,
    onError: (error) => recordError(sweep, error),
    tempDir,
  });
  for (const history of pruned) {
    sweep.result.removed.push({
      what: "Project history",
      path: join(historyRoot, history.id),
      bytes: history.bytes,
    });
  }
}

function sweepExtractCache(sweep: Sweep): void {
  const extractCache = resolveExtractCacheDir().dir;
  if (!extractCache) return;
  const swept = gcExtractionCache(extractCache, {
    maxBytes: 0,
    minAgeMs: EXTRACT_CACHE_MIN_AGE_MS,
    dryRun: sweep.dryRun,
  });
  if (swept.evictedEntries + swept.agedPartialsRemoved === 0) return;
  sweep.result.removed.push({
    what: "Extracted video frames",
    path: extractCache,
    bytes: swept.evictedBytes,
  });
}

/** Everything HyperFrames left behind that no running render or preview uses; removed unless `dryRun`. */
export async function cleanLeftovers(options: CleanOptions): Promise<CleanResult> {
  const historyRoot = options.historyRoot ?? DEFAULT_HISTORY_ROOT;
  const tempDir = options.tempDir ?? tmpdir();
  const { RENDER_JOB_DIR, listAbandonedRenderDirs, resolveRenderDebugDir } = await loadProducer();
  const sweep: Sweep = {
    dryRun: options.dryRun,
    result: { removed: [], alsoReclaimable: [], errors: [] },
  };
  const dropAbandoned = (what: string, parent: string, names?: RegExp) => {
    for (const dir of listAbandonedRenderDirs(parent, {
      ownerlessIdleMs: OWNERLESS_IDLE_MS,
      names,
    }))
      drop(sweep, what, dir);
  };

  const projects = new Set(
    [options.projectDir, ...knownProjectDirs(sweep, historyRoot)].map(realDir),
  );
  const renderParents = new Set([
    ...[...projects].flatMap((project) => [project, join(project, "renders")]),
    realDir(tempDir),
  ]);
  for (const parent of renderParents) dropAbandoned("Render leftovers", parent);
  dropAbandoned("Debug renders", options.debugDir ?? resolveRenderDebugDir(), RENDER_JOB_DIR);
  for (const project of projects) {
    if (!isProject(project)) continue;
    await attempt(sweep, () => sweepProxies(sweep, project));
    sweepSnapshots(sweep, project, options.snapshots);
  }
  await attempt(sweep, () => sweepHistories(sweep, historyRoot, tempDir));
  await attempt(sweep, () => sweepExtractCache(sweep));
  return sweep.result;
}

function printTable(rows: Leftover[]): void {
  const whatWidth = Math.max(...rows.map((row) => row.what.length));
  for (const row of rows) {
    console.log(
      `  ${row.what.padEnd(whatWidth)}  ${formatBytes(row.bytes).padStart(9)}  ${c.dim(row.path)}`,
    );
  }
}

const total = (rows: Leftover[]) => rows.reduce((sum, row) => sum + row.bytes, 0);
const redactPaths = (rows: Leftover[]) =>
  rows.map((row) => ({ ...row, path: redactHome(row.path) }));

export default defineCommand({
  meta: { name: "clean", description: "Find and remove what HyperFrames left on disk" },
  args: {
    dir: {
      type: "positional",
      description: "Project directory (default: current); its subfolders are not searched",
      required: false,
    },
    "dry-run": {
      type: "boolean",
      description: "List what would be removed, remove nothing",
      default: false,
    },
    snapshots: {
      type: "boolean",
      description: "Also remove snapshots/ and .hyperframes/artifacts/{snapshots,checks}/ folders",
      default: false,
    },
    json: { type: "boolean", description: "Output as JSON", default: false },
  },
  async run({ args }) {
    const dryRun = args["dry-run"];
    const result = await cleanLeftovers({
      projectDir: args.dir ?? process.cwd(),
      dryRun,
      snapshots: args.snapshots,
    });
    if (result.errors.length > 0) setCommandExitCode(1);
    if (args.json) {
      const report = withMeta({
        dryRun,
        removed: redactPaths(result.removed),
        alsoReclaimable: redactPaths(result.alsoReclaimable),
        errors: result.errors.map(redactHome),
        totalBytes: total(result.removed),
      });
      console.log(JSON.stringify(report, null, 2));
      return;
    }
    if (result.removed.length === 0) {
      console.log(`${c.success("◇")}  Nothing to clean`);
    } else {
      console.log(
        `${c.success("◇")}  ${dryRun ? "Would remove" : "Removed"} ${formatBytes(total(result.removed))}`,
      );
      printTable(result.removed);
    }
    if (result.alsoReclaimable.length > 0) {
      console.log(
        `\n   Also reclaimable with --snapshots: ${formatBytes(total(result.alsoReclaimable))}`,
      );
      printTable(result.alsoReclaimable);
    }
    for (const error of result.errors) console.log(c.warn(`  ${error}`));
  },
});