Skip to content

Write HTML. Render video. Built for agents.

20.9 KB
Raw Blame
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import * as clack from "@clack/prompts";
import { afterEach, describe, expect, it, vi } from "vitest";
import { runCommand } from "citty";
import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";
import { PreviewPortUnavailableError } from "./previewLifecycle.js";
import {
  default as previewCommand,
  backgroundStartFailureCode,
  foregroundPreviewReadyPayload,
  prebuildPreview,
  handlePreviewKillAll,
  handlePreviewList,
  previewHostAppError,
  previewLaunchMode,
  previewLaunchModeError,
  previewPortError,
  publicPreviewPid,
  previewViteArgs,
  reportPreviewShutdown,
  studioReadyUrl,
  studioDeepLink,
  studioSummaryUrls,
  waitForStudioChildClose,
} from "./preview.js";

const lint = vi.hoisted(() => ({ inProcess: vi.fn(), worker: vi.fn() }));
vi.mock("../utils/lintProject.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("../utils/lintProject.js")>()),
  lintProject: lint.inProcess,
}));
vi.mock("../utils/cancellableProcess.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("../utils/cancellableProcess.js")>()),
  runRenderSetupWorker: lint.worker,
}));
// The real cleanup kills every orphaned Chrome the user owns, so no test may reach it.
const killOrphanedProcesses = vi.hoisted(() => vi.fn(() => 0));
vi.mock("../utils/orphanCleanup.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("../utils/orphanCleanup.js")>()),
  killOrphanedProcesses,
}));

const tempDirs: string[] = [];

afterEach(() => {
  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
  vi.restoreAllMocks();
  process.exitCode = undefined;
});

function tempProject(): string {
  const dir = mkdtempSync(join(tmpdir(), "hf-preview-"));
  tempDirs.push(dir);
  return dir;
}

describe("Studio handoff URLs", () => {
  it("hands off the exact timeline project route", () => {
    expect(studioDeepLink("http://127.0.0.1:3002", "demo")).toBe(
      "http://127.0.0.1:3002/#project/demo",
    );
    expect(studioSummaryUrls("demo", "http://127.0.0.1:3002")).toEqual({
      serverUrl: "http://127.0.0.1:3002",
      studioUrl: "http://127.0.0.1:3002/#project/demo",
    });
  });

  it("URL-encodes project names that have hash-route metacharacters", () => {
    expect(studioDeepLink("http://127.0.0.1:3002", "Launch #1? 50%")).toBe(
      "http://127.0.0.1:3002/#project/Launch%20%231%3F%2050%25",
    );
  });
});

describe("preview --kill-all", () => {
  const session = (port: number, projectDir: string) => ({
    pid: 4321,
    port,
    projectDir,
    logPath: `${projectDir}.log`,
  });

  it("keeps stopping after a record whose ownership cannot be proven", async () => {
    // Propagating the first failure left every later preview running AND
    // unreported — the one thing a stop pass must never do.
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    const warn = vi.spyOn(clack.log, "warn").mockImplementation(() => {});

    await handlePreviewKillAll(3002, false, {
      listManaged: async () => [session(41402, "/tmp/unprovable"), session(41403, "/tmp/healthy")],
      stopManaged: async (projectDir: string) => {
        if (projectDir === "/tmp/unprovable") throw new Error("ownership failed");
        return true;
      },
      killScanned: async () => ({ killed: 0, unverified: [] }),
    });

    expect(log.mock.calls.flat().join("\n")).toContain("Killed 1 preview server");
    expect(warn.mock.calls.flat().join("\n")).toContain("/tmp/unprovable: ownership failed");
    log.mockRestore();
    warn.mockRestore();
  });

  it("reports nothing to kill when no preview is running", async () => {
    const log = vi.spyOn(console, "log").mockImplementation(() => {});

    await handlePreviewKillAll(3002, false, {
      listManaged: async () => [],
      killScanned: async () => ({ killed: 0, unverified: [] }),
    });

    expect(log.mock.calls.flat().join("\n")).toContain("No active preview servers to kill");
    log.mockRestore();
  });
});

describe("previewLaunchMode", () => {
  it.each([
    [
      {
        background: false,
        foreground: false,
        interactive: false,
        devMode: false,
        localStudio: false,
      },
      "background",
    ],
    [
      {
        background: false,
        foreground: false,
        interactive: true,
        devMode: false,
        localStudio: false,
      },
      "embedded",
    ],
    [
      {
        background: false,
        foreground: true,
        interactive: false,
        devMode: true,
        localStudio: false,
      },
      "dev",
    ],
    [
      {
        background: false,
        foreground: true,
        interactive: false,
        devMode: false,
        localStudio: true,
      },
      "local",
    ],
    [
      {
        background: true,
        foreground: false,
        interactive: true,
        devMode: true,
        localStudio: true,
      },
      "background",
    ],
  ] as const)("resolves %o to %s", (options, expected) => {
    expect(previewLaunchMode(options)).toBe(expected);
  });

  it("rejects conflicting lifecycle overrides and actions", () => {
    expect(
      previewLaunchModeError({
        background: true,
        foreground: true,
        status: false,
        stop: false,
        list: false,
        killAll: false,
      }),
    ).toBe("--background and --foreground cannot be used together");
    expect(
      previewLaunchModeError({
        background: false,
        foreground: false,
        status: true,
        stop: true,
        list: false,
        killAll: false,
      }),
    ).toBe("Only one of --status, --stop, --list, or --kill-all can be used at a time");
    expect(
      previewLaunchModeError({
        background: true,
        foreground: false,
        status: false,
        stop: false,
        list: false,
        killAll: false,
      }),
    ).toBeNull();
    expect(
      previewLaunchModeError({
        background: true,
        foreground: false,
        status: true,
        stop: false,
        list: false,
        killAll: false,
      }),
    ).toBe("Preview launch overrides cannot be combined with lifecycle actions");
    expect(
      previewLaunchModeError({
        background: false,
        foreground: true,
        status: false,
        stop: false,
        list: false,
        killAll: true,
      }),
    ).toBe("Preview launch overrides cannot be combined with lifecycle actions");
    expect(
      previewLaunchModeError({
        background: false,
        foreground: false,
        forceNew: true,
        status: true,
        stop: false,
        list: false,
        killAll: false,
      }),
    ).toBe("Preview launch overrides cannot be combined with lifecycle actions");
  });

  it.each([
    [undefined, null],
    ["3002", null],
    ["1", null],
    ["65535", null],
    ["banana", "--port must be an integer between 1 and 65535"],
    ["3002oops", "--port must be an integer between 1 and 65535"],
    ["0", "--port must be an integer between 1 and 65535"],
    ["65536", "--port must be an integer between 1 and 65535"],
  ])("validates preview port %j", (value, expected) => {
    expect(previewPortError(value)).toBe(expected);
  });

  it("prefers the live server PID over its launcher PID", () => {
    expect(publicPreviewPid("9876", 4321)).toBe(9876);
    expect(publicPreviewPid(null, 4321)).toBe(4321);
  });

  it("pins detached Vite to the port the lifecycle scanner waits on", () => {
    expect(previewViteArgs(3032)).toEqual(["--host", "127.0.0.1", "--port", "3032"]);
  });

  it.each([
    ["  Local:   http://localhost:43127/", "http://localhost:43127"],
    ["  Local:   http://127.0.0.1:43127/", "http://127.0.0.1:43127"],
    [
      "\u001b[32m  Local:\u001b[0m   \u001b[36mhttp://127.0.0.1:43127/\u001b[0m",
      "http://127.0.0.1:43127",
    ],
  ])("extracts the ready URL from Vite output %j", (output, expected) => {
    expect(studioReadyUrl(output)).toBe(expected);
  });
});

describe("preview lifecycle JSON failures", () => {
  it.each([
    [
      "list",
      () =>
        handlePreviewList(3002, true, {
          scan: async () => {
            throw new Error("list probe failed");
          },
          listManaged: async () => [],
        }),
      "preview-list-failed",
    ],
    [
      "kill-all",
      () =>
        handlePreviewKillAll(3002, true, {
          listManaged: async () => [],
          killScanned: async () => {
            throw new Error("scan failed");
          },
        }),
      "preview-kill-all-failed",
    ],
  ] as const)("wraps %s failures in one JSON document", async (operation, run, code) => {
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    const error = vi.spyOn(console, "error").mockImplementation(() => {});

    await run();

    expect(log).toHaveBeenCalledOnce();
    const [line] = log.mock.calls[0] as [string];
    expect(JSON.parse(line)).toMatchObject({
      schemaVersion: 1,
      operation,
      ok: false,
      error: { code },
    });
    expect(error).not.toHaveBeenCalled();
  });

  it("keeps stopping after a record whose ownership cannot be proven", async () => {
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    const session = (port: number, projectDir: string) => ({
      pid: 4321,
      port,
      projectDir,
      logPath: `${projectDir}.log`,
    });

    await handlePreviewKillAll(3002, true, {
      listManaged: async () => [session(41402, "/tmp/unprovable"), session(41403, "/tmp/healthy")],
      stopManaged: async (projectDir) => {
        if (projectDir === "/tmp/unprovable") throw new Error("ownership failed");
        return true;
      },
      killScanned: async () => ({ killed: 0, unverified: [] }),
    });

    const [line] = log.mock.calls[0] as [string];
    // The second record must still be stopped AND the first must be reported:
    // propagating the first failure left every later preview running, unlisted.
    expect(JSON.parse(line)).toMatchObject({
      operation: "kill-all",
      ok: true,
      result: { state: "killed-all", stopped: 1, failed: ["/tmp/unprovable: ownership failed"] },
    });
  });

  it("wraps managed-start validation failures in one JSON document", async () => {
    const dir = tempProject();
    writeFileSync(join(dir, "index.html"), "<html></html>");
    const log = vi.spyOn(console, "log").mockImplementation(() => {});

    await runCommand(previewCommand, {
      rawArgs: [dir, "--background", "--json", "--user-data-dir", join(dir, "profile")],
    });

    expect(log).toHaveBeenCalledOnce();
    const [line] = log.mock.calls[0] as [string];
    expect(JSON.parse(line)).toMatchObject({
      schemaVersion: 1,
      operation: "start",
      ok: false,
      error: { code: "preview-validation-failed" },
    });
  });

  it("wraps stop failures in one JSON document", async () => {
    const missing = join(tmpdir(), `hf-preview-missing-${process.pid}-${Date.now()}`);
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    const error = vi.spyOn(console, "error").mockImplementation(() => {});

    await runCommand(previewCommand, {
      rawArgs: [missing, "--stop", "--json"],
    });

    expect(log).toHaveBeenCalledOnce();
    const [line] = log.mock.calls[0] as [string];
    expect(JSON.parse(line)).toMatchObject({
      schemaVersion: 1,
      operation: "stop",
      ok: false,
      error: { code: "preview-stop-failed" },
    });
    expect(error).not.toHaveBeenCalled();
  });

  it.each([
    [new PreviewServerPortMismatchError(3500, []), "preview-port-mismatch"],
    [new PreviewPortUnavailableError(3500, 3501), "preview-port-unavailable"],
    [new Error("spawn failed"), "preview-start-failed"],
  ])("maps a background start failure to its JSON code (%#)", (error, code) => {
    expect(backgroundStartFailureCode(error)).toBe(code);
  });

  it("wraps missing-project start failures without human stderr", async () => {
    const missing = join(tmpdir(), `hf-preview-missing-start-${process.pid}-${Date.now()}`);
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    const error = vi.spyOn(console, "error").mockImplementation(() => {});

    await runCommand(previewCommand, { rawArgs: [missing, "--background", "--json"] });

    expect(log).toHaveBeenCalledOnce();
    const [line] = log.mock.calls[0] as [string];
    expect(JSON.parse(line)).toMatchObject({
      operation: "start",
      ok: false,
      error: { code: "preview-start-failed" },
    });
    expect(error).not.toHaveBeenCalled();
  });
});

describe("prebuildPreview", () => {
  it("asks the server for the opening film's preview document", async () => {
    const fetchApp = vi.fn(async (_request: Request) => new Response(""));

    await prebuildPreview(fetchApp, "http://localhost:3002", "Launch #1");

    expect(fetchApp.mock.calls[0]![0].url).toBe(
      "http://localhost:3002/api/projects/Launch%20%231/preview",
    );
  });

  it("does not fail the start when the build throws", async () => {
    const fetchApp = vi.fn(() => {
      throw new Error("bundle failed");
    });

    await expect(prebuildPreview(fetchApp, "http://localhost:3002", "demo")).resolves.toBe(
      undefined,
    );
  });
});

describe("startup lint", () => {
  const neverSettles = () => new Promise<never>(() => {});

  it("never lints for a --json start", async () => {
    lint.inProcess.mockImplementation(neverSettles);
    lint.worker.mockImplementation(neverSettles);
    const dir = tempProject();
    writeFileSync(join(dir, "index.html"), "<html></html>");
    vi.spyOn(console, "log").mockImplementation(() => {});

    await runCommand(previewCommand, {
      rawArgs: [dir, "--background", "--json", "--user-data-dir", join(dir, "profile")],
    });

    expect(lint.inProcess).not.toHaveBeenCalled();
    expect(lint.worker).not.toHaveBeenCalled();
  });

  it("does not hold a start behind a lint that has not finished", async () => {
    lint.inProcess.mockImplementation(neverSettles);
    lint.worker.mockImplementation(neverSettles);
    const dir = tempProject();
    writeFileSync(join(dir, "index.html"), "<html></html>");
    const error = vi.spyOn(clack.log, "error").mockImplementation(() => {});

    await runCommand(previewCommand, {
      rawArgs: [dir, "--background", "--user-data-dir", join(dir, "profile")],
    });

    expect(error).toHaveBeenCalledWith(expect.stringContaining("--user-data-dir"));
    expect(lint.inProcess).not.toHaveBeenCalled();
  }, 5_000);
});

describe("foreground preview JSON", () => {
  it("emits the same ready session contract before remaining attached", () => {
    const dir = tempProject();
    expect(foregroundPreviewReadyPayload("Launch #1", "http://localhost:4567", dir, 4321)).toEqual({
      schemaVersion: 1,
      operation: "start",
      ok: true,
      result: {
        state: "started",
        mode: "foreground",
        projectName: "Launch #1",
        projectDir: dir,
        host: "127.0.0.1",
        port: 4567,
        pid: 4321,
        serverUrl: "http://127.0.0.1:4567",
        studioUrl: "http://127.0.0.1:4567/#project/Launch%20%231",
        ready: true,
      },
    });
  });

  it("keeps embedded shutdown silent after the readiness envelope", () => {
    const log = vi.spyOn(console, "log").mockImplementation(() => {});

    reportPreviewShutdown(true);

    expect(log).not.toHaveBeenCalled();
  });
});

describe("waitForStudioChildClose", () => {
  it("resolves when the child closed before the listener was attached", async () => {
    const signalTarget = { once: vi.fn(), off: vi.fn() };
    const child = {
      exitCode: 1,
      signalCode: null,
      once: vi.fn(),
    } as unknown as Parameters<typeof waitForStudioChildClose>[0];

    await expect(waitForStudioChildClose(child, signalTarget)).resolves.toBeUndefined();
    expect(child.once).not.toHaveBeenCalled();
    expect(signalTarget.once).toHaveBeenCalledTimes(3);
    expect(signalTarget.off).toHaveBeenCalledTimes(3);
  });

  it("reaps the dev server when the terminal closes (SIGHUP)", async () => {
    const signalTarget = { once: vi.fn(), off: vi.fn() };
    const child = { exitCode: 0, signalCode: null, once: vi.fn() } as unknown as Parameters<
      typeof waitForStudioChildClose
    >[0];

    await waitForStudioChildClose(child, signalTarget);

    const hupListener = signalTarget.once.mock.calls.find(([event]) => event === "SIGHUP")?.[1];
    expect(hupListener).toBeTypeOf("function");
    expect(signalTarget.off).toHaveBeenCalledWith("SIGHUP", hupListener);
  });

  it("reaps on process exit even when stdio never emits close", async () => {
    let exit: (() => void) | undefined;
    const signalTarget = { once: vi.fn(), off: vi.fn() };
    const child = {
      exitCode: null,
      signalCode: null,
      once: vi.fn((event: string, listener: () => void) => {
        if (event === "exit") exit = listener;
      }),
    } as unknown as Parameters<typeof waitForStudioChildClose>[0];

    let resolved = false;
    const waiting = waitForStudioChildClose(child, signalTarget).then(() => {
      resolved = true;
    });

    await Promise.resolve();
    expect(resolved).toBe(false);
    expect(child.once).toHaveBeenCalledWith("exit", expect.any(Function));

    exit?.();
    await waiting;
    expect(resolved).toBe(true);
    expect(signalTarget.off).toHaveBeenCalledTimes(3);
  });
});

describe("studio dev-server spawns", () => {
  function fakeStudioChild() {
    return {
      pid: 4321,
      exitCode: 0,
      signalCode: null,
      stdout: { on: vi.fn(), removeListener: vi.fn() },
      stderr: { on: vi.fn(), removeListener: vi.fn() },
      on: vi.fn(),
      once: vi.fn(),
    };
  }

  // Returns the spawn spy. mkdirSync/existsSync are stubbed too, so
  // linkProjectIntoStudioData never touches the real studio data directory.
  function mockStudioSpawn() {
    const spawn = vi.fn((_command: string, _args: string[], _options: unknown) =>
      fakeStudioChild(),
    );
    vi.doMock("node:child_process", async (importOriginal) => {
      const actual = await importOriginal<typeof import("node:child_process")>();
      return { ...actual, spawn };
    });
    vi.doMock("node:fs", async (importOriginal) => {
      const actual = await importOriginal<typeof import("node:fs")>();
      return { ...actual, mkdirSync: () => undefined, existsSync: () => true };
    });
    vi.resetModules();
    return spawn;
  }

  afterEach(() => {
    vi.doUnmock("node:child_process");
    vi.doUnmock("node:fs");
    vi.resetModules();
  });

  it("runDevMode passes windowsHide to the studio dev-server spawn", async () => {
    const spawn = mockStudioSpawn();

    const { runDevMode } = await import("./preview.js");
    await runDevMode("/tmp/hf-preview-devmode-test", { json: true });

    expect(spawn).toHaveBeenCalledOnce();
    expect(spawn.mock.calls[0]?.[2]).toMatchObject({ windowsHide: true });
  });

  it("runLocalStudioMode passes windowsHide to the local Vite spawn", async () => {
    const spawn = mockStudioSpawn();

    // @hyperframes/studio is resolved for real, so the project dir has to sit
    // inside the monorepo's node_modules tree.
    const thisFile = fileURLToPath(import.meta.url);
    const localStudioProjectDir = resolve(dirname(thisFile), "..", "..");
    const { runLocalStudioMode } = await import("./preview.js");
    await runLocalStudioMode(localStudioProjectDir, { json: true });

    expect(spawn).toHaveBeenCalledOnce();
    expect(spawn.mock.calls[0]?.[2]).toMatchObject({ windowsHide: true });
  });
});

describe("preview inside a host app's agent run", () => {
  const hostRun = { HYPERFRAMES_DESKTOP_PROJECT: "/projects/demo" };

  it("refuses a background preview, which would outlive the run", () => {
    expect(previewHostAppError("background", hostRun)).toMatch(/host app .* owns its preview/);
    expect(previewHostAppError("background", hostRun)).toContain("--foreground");
  });

  it("allows a preview attached to the run, and background outside a host app", () => {
    expect(previewHostAppError("embedded", hostRun)).toBeNull();
    expect(previewHostAppError("local", hostRun)).toBeNull();
    expect(previewHostAppError("background", {})).toBeNull();
  });

  it("refuses before spawning anything", async () => {
    vi.stubEnv("HYPERFRAMES_DESKTOP_PROJECT", "/projects/demo");
    const project = mkdtempSync(join(tmpdir(), "hf-host-preview-"));
    writeFileSync(join(project, "index.html"), "<html><body></body></html>");
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    let printed = "";
    try {
      await runCommand(previewCommand, { rawArgs: [project, "--background", "--json"] });
      printed = String(log.mock.calls.at(-1)?.[0]);
    } finally {
      log.mockRestore();
      vi.unstubAllEnvs();
      rmSync(project, { recursive: true, force: true });
    }
    const payload = JSON.parse(printed);
    expect(payload).toMatchObject({ ok: false, error: { code: "host-app-owns-preview" } });
    expect(killOrphanedProcesses).not.toHaveBeenCalled();
  });
});