libretto 0.4.4 → 0.5.1

package/src/shared/logger/sinks.ts

@@ -0,0 +1,148 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { LoggerSink } from "./logger.js";
+
+export function createFileLogSink({
+  filePath,
+}: {
+  filePath: string;
+}): LoggerSink {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const writeStream = fs.createWriteStream(filePath, { flags: "a" });
+
+  return {
+    write: ({ id, scope, level, event, data, options }) => {
+      if (writeStream.destroyed || writeStream.writableEnded) {
+        return;
+      }
+      const timestamp = options?.timestamp || new Date();
+
+      const logEntry = {
+        timestamp: timestamp.toISOString(),
+        id,
+        level,
+        scope,
+        event,
+        data,
+      };
+
+      const jsonLine = JSON.stringify(logEntry) + "\n";
+
+      try {
+        writeStream.write(jsonLine, (error) => {
+          if (error) {
+            console.error("Failed to write to log file:", error);
+            console[level]({ id, scope, event, data, timestamp });
+          }
+        });
+      } catch (error) {
+        console.error("Failed to write to log file:", error);
+        console[level]({ id, scope, event, data, timestamp });
+      }
+    },
+    flush: () =>
+      new Promise<void>((resolve, reject) => {
+        if (
+          !writeStream.writable ||
+          writeStream.writableEnded ||
+          writeStream.destroyed
+        ) {
+          resolve();
+          return;
+        }
+        writeStream.write("", (error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve();
+          }
+        });
+      }),
+    close: () =>
+      new Promise<void>((resolve) => {
+        if (writeStream.destroyed || writeStream.closed) {
+          resolve();
+          return;
+        }
+        let settled = false;
+        const done = () => {
+          if (settled) return;
+          settled = true;
+          resolve();
+        };
+        writeStream.once("finish", done);
+        writeStream.once("close", done);
+        writeStream.once("error", done);
+        try {
+          writeStream.end();
+        } catch {
+          done();
+        }
+      }),
+  };
+}
+
+// ANSI color codes
+const colors = {
+  reset: "\x1b[0m",
+  gray: "\x1b[90m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+function formatTimestamp(date: Date): string {
+  return date.toISOString().replace("T", " ").replace("Z", "");
+}
+
+export const prettyConsoleSink: LoggerSink = {
+  write: ({ scope, level, event, data, options }) => {
+    const timestamp = `${colors.gray}${formatTimestamp(options?.timestamp || new Date())}${colors.reset}`;
+    const levelColor =
+      level === "error"
+        ? colors.red
+        : level === "warn"
+          ? colors.yellow
+          : colors.blue;
+    const coloredScope = scope ? `${colors.cyan}[${scope}]${colors.reset}` : "";
+
+    const logPrefix = `${timestamp} ${levelColor}${level.toUpperCase()}${colors.reset} ${coloredScope} ${event}`;
+
+    if (level === "error" && data.error) {
+      const { error, ...otherData } = data;
+      console.error(logPrefix);
+      if (error.stack) {
+        console.error(`  ${error.stack}`);
+      } else if (error.type && error.message) {
+        console.error(`  ${error.type}: ${error.message}`);
+      }
+      if (Object.keys(otherData).length > 0) {
+        console.error(JSON.stringify(otherData, null, 2));
+      }
+    } else {
+      console[level](logPrefix);
+      if (Object.keys(data).length > 0) {
+        console[level](JSON.stringify(data, null, 2));
+      }
+    }
+  },
+};
+
+export const jsonlConsoleSink: LoggerSink = {
+  write: ({ id, scope, level, event, data, options }) => {
+    const timestamp = options?.timestamp || new Date();
+
+    const logEntry = {
+      timestamp: timestamp.toISOString(),
+      id,
+      level,
+      scope: scope || undefined,
+      event,
+      data,
+    };
+
+    console.log(JSON.stringify(logEntry));
+  },
+};

package/src/shared/paths/paths.ts

@@ -0,0 +1,110 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveLibrettoRepoRoot } from "./repo-root.js";
+
+const LIBRETTO_DIRNAME = ".libretto";
+const LIBRETTO_SESSIONS_DIRNAME = "sessions";
+const SESSION_STATE_FILENAME = "state.json";
+const RUNNER_LOG_DIRNAME = "logs";
+const RUNNER_LOG_FILENAME = "logs.jsonl";
+const PAUSED_SIGNAL_SUFFIX = "paused";
+const RESUME_SIGNAL_SUFFIX = "resume";
+
+function getLibrettoRoot(cwd: string = process.cwd()): string {
+  return join(resolveLibrettoRepoRoot(cwd), LIBRETTO_DIRNAME);
+}
+
+function getLibrettoSessionsDir(cwd: string = process.cwd()): string {
+  return join(getLibrettoRoot(cwd), LIBRETTO_SESSIONS_DIRNAME);
+}
+
+function getLibrettoSessionDir(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return join(getLibrettoSessionsDir(cwd), sessionName);
+}
+
+function getLibrettoSessionStatePath(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return join(getLibrettoSessionDir(sessionName, cwd), SESSION_STATE_FILENAME);
+}
+
+export function getLibrettoPauseSignalDir(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return getLibrettoSessionDir(sessionName, cwd);
+}
+
+function getLibrettoRunnerLogDir(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return join(getLibrettoSessionDir(sessionName, cwd), RUNNER_LOG_DIRNAME);
+}
+
+export function getRunnerLogPathForDir(logDir: string): string {
+  return join(logDir, RUNNER_LOG_FILENAME);
+}
+
+export function getPauseSignalPathForDir(
+  signalDir: string,
+  sessionName: string,
+  signal: "paused" | "resume",
+): string {
+  const suffix =
+    signal === "paused" ? PAUSED_SIGNAL_SUFFIX : RESUME_SIGNAL_SUFFIX;
+  return join(signalDir, `${sessionName}.${suffix}`);
+}
+
+export function getLibrettoPausedSignalPath(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "paused",
+  );
+}
+
+export function getLibrettoResumeSignalPath(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "resume",
+  );
+}
+
+export function ensureLibrettoSessionStatePath(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  const filePath = getLibrettoSessionStatePath(sessionName, cwd);
+  mkdirSync(dirname(filePath), { recursive: true });
+  return filePath;
+}
+
+export function ensureLibrettoPauseSignalDir(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  const dir = getLibrettoPauseSignalDir(sessionName, cwd);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function ensureLibrettoRunnerLogDir(
+  sessionName: string,
+  cwd: string = process.cwd(),
+): string {
+  const dir = getLibrettoRunnerLogDir(sessionName, cwd);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/src/shared/paths/repo-root.ts

@@ -0,0 +1,27 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+const repoRootCache = new Map<string, string>();
+
+export function resolveLibrettoRepoRoot(cwd: string = process.cwd()): string {
+  const override = process.env.LIBRETTO_REPO_ROOT?.trim();
+  if (override) {
+    return resolve(override);
+  }
+
+  const normalizedCwd = resolve(cwd);
+  const cached = repoRootCache.get(normalizedCwd);
+  if (cached) {
+    return cached;
+  }
+
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: normalizedCwd,
+    encoding: "utf-8",
+  });
+
+  const repoRoot =
+    result.status === 0 && result.stdout ? result.stdout.trim() : normalizedCwd;
+  repoRootCache.set(normalizedCwd, repoRoot);
+  return repoRoot;
+}

package/src/shared/run/api.ts

@@ -0,0 +1,6 @@
+// --- Browser ---
+export {
+  launchBrowser,
+  type LaunchBrowserArgs,
+  type BrowserSession,
+} from "./browser.js";

package/src/shared/run/browser.ts

@@ -0,0 +1,107 @@
+import {
+  chromium,
+  type Browser,
+  type BrowserContext,
+  type Page,
+} from "playwright";
+import { createServer } from "node:net";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ensureLibrettoSessionStatePath } from "../paths/paths.js";
+import {
+  SESSION_STATE_VERSION,
+  SessionStateFileSchema,
+} from "../state/session-state.js";
+
+async function pickFreePort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        server.close(() => resolve(addr.port));
+        return;
+      }
+      server.close(() => reject(new Error("Failed to resolve debug port")));
+    });
+  });
+}
+
+export type LaunchBrowserArgs = {
+  sessionName: string;
+  headless?: boolean;
+  viewport?: { width: number; height: number };
+  storageStatePath?: string;
+};
+
+export type BrowserSession = {
+  browser: Browser;
+  context: BrowserContext;
+  page: Page;
+  debugPort: number;
+  metadataPath: string;
+  close: () => Promise<void>;
+};
+
+export async function launchBrowser({
+  sessionName,
+  headless = false,
+  viewport = { width: 1366, height: 768 },
+  storageStatePath,
+}: LaunchBrowserArgs): Promise<BrowserSession> {
+  const debugPort = await pickFreePort();
+  const browser = await chromium.launch({
+    headless,
+    args: [
+      "--disable-blink-features=AutomationControlled",
+      `--remote-debugging-port=${debugPort}`,
+      "--no-focus-on-check",
+    ],
+  });
+
+  const context = await browser.newContext({
+    viewport,
+    ...(storageStatePath ? { storageState: storageStatePath } : {}),
+  });
+  const page = await context.newPage();
+  page.setDefaultTimeout(30_000);
+  page.setDefaultNavigationTimeout(45_000);
+
+  const metadataPath = ensureLibrettoSessionStatePath(sessionName);
+  const existingStateRaw = existsSync(metadataPath)
+    ? (JSON.parse(readFileSync(metadataPath, "utf-8")) as unknown)
+    : undefined;
+
+  const parsedExistingState =
+    SessionStateFileSchema.safeParse(existingStateRaw);
+
+  writeFileSync(
+    metadataPath,
+    JSON.stringify(
+      {
+        version: parsedExistingState.success
+          ? parsedExistingState.data.version
+          : SESSION_STATE_VERSION,
+        session: sessionName,
+        port: debugPort,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        status: "active",
+      },
+      null,
+      2,
+    ),
+  );
+
+  return {
+    browser,
+    context,
+    page,
+    debugPort,
+    metadataPath,
+    close: async () => {
+      await browser.close();
+    },
+  };
+}

package/src/shared/state/index.ts

@@ -0,0 +1,11 @@
+export {
+  SESSION_STATE_VERSION,
+  SessionStatusSchema,
+  SessionStateFileSchema,
+  parseSessionStateData,
+  parseSessionStateContent,
+  serializeSessionState,
+  type SessionStatus,
+  type SessionState,
+  type SessionStateFile,
+} from "./session-state.js";

package/src/shared/state/session-state.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+export const SESSION_STATE_VERSION = 1;
+
+export const SessionStatusSchema = z.enum([
+  "active",
+  "paused",
+  "completed",
+  "failed",
+  "exited",
+]);
+export const SessionViewportSchema = z.object({
+  width: z.number().int().min(1),
+  height: z.number().int().min(1),
+});
+
+export const SessionStateFileSchema = z.object({
+  version: z.literal(SESSION_STATE_VERSION),
+  port: z.number().int().min(0).max(65535),
+  pid: z.number().int().optional(),
+  cdpEndpoint: z.string().url().optional(),
+  session: z.string().min(1),
+  startedAt: z.string().datetime({ offset: true }),
+  status: SessionStatusSchema.optional(),
+  viewport: SessionViewportSchema.optional(),
+});
+
+export type SessionStatus = z.infer<typeof SessionStatusSchema>;
+export type SessionStateFile = z.infer<typeof SessionStateFileSchema>;
+export type SessionState = Omit<SessionStateFile, "version">;
+
+function formatIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.join(".") || "root";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}
+
+export function parseSessionStateData(
+  rawState: unknown,
+  source: string,
+): SessionState {
+  const parsed = SessionStateFileSchema.safeParse(rawState);
+  if (!parsed.success) {
+    throw new Error(
+      `Session state at ${source} is invalid: ${formatIssues(parsed.error)}`,
+    );
+  }
+
+  const { version: _version, ...state } = parsed.data;
+  return state;
+}
+
+export function parseSessionStateContent(
+  content: string,
+  source: string,
+): SessionState {
+  let rawState: unknown;
+  try {
+    rawState = JSON.parse(content);
+  } catch (error) {
+    throw new Error(
+      `Session state at ${source} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return parseSessionStateData(rawState, source);
+}
+
+export function serializeSessionState(state: SessionState): SessionStateFile {
+  return SessionStateFileSchema.parse({
+    version: SESSION_STATE_VERSION,
+    ...state,
+  });
+}

package/src/shared/visualization/ghost-cursor.ts

@@ -0,0 +1,213 @@
+import type { Page } from "playwright";
+
+export type GhostCursorStyle = "minimal" | "dot" | "screenstudio";
+
+export type GhostCursorOptions = {
+  style?: GhostCursorStyle;
+  color?: string;
+  size?: number;
+  zIndex?: number;
+  easing?: string;
+  minDurationMs?: number;
+  maxDurationMs?: number;
+  speedPxPerMs?: number;
+};
+
+const DEFAULTS: Required<GhostCursorOptions> = {
+  style: "minimal",
+  color: "rgba(255, 70, 70, 0.9)",
+  size: 20,
+  zIndex: 2147483646,
+  easing: "cubic-bezier(0.16, 1, 0.3, 1)",
+  minDurationMs: 100,
+  maxDurationMs: 600,
+  speedPxPerMs: 1.5,
+};
+
+const CURSOR_ID = "__libretto_ghost_cursor__";
+
+function buildCursorSvg(
+  style: GhostCursorStyle,
+  color: string,
+  size: number,
+): string {
+  if (style === "dot") {
+    return `<div style="width:${size}px;height:${size}px;border-radius:50%;background:${color};"></div>`;
+  }
+  if (style === "screenstudio") {
+    return `<div style="width:${size * 1.4}px;height:${size * 1.4}px;border-radius:50%;background:${color};box-shadow:0 0 ${size * 0.6}px ${color};opacity:0.7;"></div>`;
+  }
+  // minimal: default arrow-like SVG cursor
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+		<path d="M5 3L19 12L12 13L9 20L5 3Z" fill="${color}" stroke="rgba(0,0,0,0.3)" stroke-width="1"/>
+	</svg>`;
+}
+
+function buildInitScript(opts: Required<GhostCursorOptions>): string {
+  const svg = buildCursorSvg(opts.style, opts.color, opts.size);
+  return `
+(function() {
+	if (document.getElementById("${CURSOR_ID}")) return;
+	var el = document.createElement("div");
+	el.id = "${CURSOR_ID}";
+	el.style.cssText = "position:fixed;top:0;left:0;z-index:${opts.zIndex};pointer-events:none;transform:translate3d(-100px,-100px,0);transition:none;will-change:transform,opacity;opacity:0;";
+	el.innerHTML = ${JSON.stringify(svg)};
+	document.documentElement.appendChild(el);
+})();
+`;
+}
+
+const installedPages = new WeakSet<Page>();
+
+export async function ensureGhostCursor(
+  page: Page,
+  options?: GhostCursorOptions,
+): Promise<void> {
+  const existingOpts = (page as any).__librettoGhostCursorOpts as
+    | Required<GhostCursorOptions>
+    | undefined;
+  const opts = { ...DEFAULTS, ...(existingOpts ?? {}), ...options };
+  const initScript = buildInitScript(opts);
+
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+
+  // Store options on the page for later use by move/click
+  (page as any).__librettoGhostCursorOpts = opts;
+
+  // Re-run in-page installer so cursor recovers after page.setContent() or DOM resets.
+  try {
+    await page.evaluate(new Function(initScript) as () => void);
+  } catch {
+    // Page might not be ready yet; addInitScript will handle on next navigation
+  }
+}
+
+export async function moveGhostCursor(
+  page: Page,
+  target: { x: number; y: number; durationMs?: number },
+): Promise<void> {
+  const opts: Required<GhostCursorOptions> =
+    (page as any).__librettoGhostCursorOpts ?? DEFAULTS;
+
+  const durationMs =
+    target.durationMs ??
+    Math.min(
+      opts.maxDurationMs,
+      Math.max(opts.minDurationMs, 200), // default ~200ms if no distance info
+    );
+
+  try {
+    await page.evaluate(
+      ({ id, x, y, duration, easing }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.opacity = "1";
+        el.style.transition = `transform ${duration}ms ${easing}`;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+      },
+      {
+        id: CURSOR_ID,
+        x: target.x,
+        y: target.y,
+        duration: durationMs,
+        easing: opts.easing,
+      },
+    );
+
+    await page.waitForTimeout(durationMs);
+  } catch {
+    // Best-effort: page may have navigated
+  }
+}
+
+export async function moveGhostCursorWithDistance(
+  page: Page,
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+): Promise<void> {
+  const opts: Required<GhostCursorOptions> =
+    (page as any).__librettoGhostCursorOpts ?? DEFAULTS;
+
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  const durationMs = Math.min(
+    opts.maxDurationMs,
+    Math.max(opts.minDurationMs, distance / opts.speedPxPerMs),
+  );
+
+  await moveGhostCursor(page, { x: to.x, y: to.y, durationMs });
+}
+
+export async function ghostClick(
+  page: Page,
+  target: { x: number; y: number },
+): Promise<void> {
+  try {
+    // Click feedback: scale down on "press"
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(0.93)`;
+        el.style.transition = "transform 80ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y },
+    );
+    await page.waitForTimeout(100);
+
+    // Release: scale back up
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(1)`;
+        el.style.transition = "transform 120ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y },
+    );
+    await page.waitForTimeout(130);
+  } catch {
+    // Best-effort
+  }
+}
+
+export async function hideGhostCursor(page: Page): Promise<void> {
+  try {
+    await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transition = "opacity 300ms ease-out";
+        el.style.opacity = "0";
+      },
+      { id: CURSOR_ID },
+    );
+  } catch {
+    // Best-effort
+  }
+}
+
+export async function getGhostCursorPosition(
+  page: Page,
+): Promise<{ x: number; y: number } | null> {
+  try {
+    return await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return null;
+        const match = el.style.transform.match(
+          /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/,
+        );
+        if (!match) return null;
+        return { x: parseFloat(match[1]!), y: parseFloat(match[2]!) };
+      },
+      { id: CURSOR_ID },
+    );
+  } catch {
+    return null;
+  }
+}