libretto 0.6.24 → 0.6.26

package/src/cli/core/workflow-runner/runner.ts

@@ -1,10 +1,15 @@
-import type { BrowserContext, Page } from "playwright";
+import type { BrowserContext, Frame, Page } from "playwright";
 import type { LoggerApi } from "../../../shared/logger/index.js";
 import { installPauseHandler } from "../../../shared/debug/pause-handler.js";
+import {
+  mergeAuthProfileStorageState,
+  normalizeAuthProfileSite,
+} from "../../../shared/workflow/auth-profile-state.js";
 import type {
   ExportedLibrettoWorkflow,
   LibrettoWorkflowContext,
 } from "../../../shared/workflow/workflow.js";
+import { readProfile, writeProfile } from "../profiles.js";
 import {
   getAbsoluteIntegrationPath,
   installHeadedWorkflowVisualization,
@@ -44,6 +49,7 @@ export type WorkflowControllerConfig = {
   page: Page;
   context: BrowserContext;
   logger: LoggerApi;
+  refreshLocalAuthProfiles?: boolean;
   onLog?: (event: WorkflowLogEvent) => void;
   onOutcome?: (outcome: WorkflowOutcome) => void;
 };
@@ -155,6 +161,7 @@ export class WorkflowController {
         session: this.config.session,
         page: this.config.page,
       };
+      const visitedSites = createVisitedSiteTracker(this.config.context);
 
       const uninstallPauseHandler = installPauseHandler((pauseArgs) =>
         this.pause({
@@ -164,6 +171,12 @@ export class WorkflowController {
       );
       try {
         await workflow.run(workflowContext, workflowConfig.params ?? {});
+        await refreshLocalAuthProfileIfEnabled({
+          context: this.config.context,
+          enabled: this.config.refreshLocalAuthProfiles === true,
+          sites: visitedSites.sites(),
+          workflow,
+        });
       } catch (error) {
         this.emitOutcome({
           state: "finished",
@@ -174,6 +187,7 @@ export class WorkflowController {
         return;
       } finally {
         uninstallPauseHandler();
+        visitedSites.dispose();
       }
 
       this.emitOutcome({
@@ -232,6 +246,77 @@ export class WorkflowController {
   }
 }
 
+async function refreshLocalAuthProfileIfEnabled(
+  args: {
+    context: BrowserContext;
+    enabled: boolean;
+    sites: readonly string[];
+    workflow: ExportedLibrettoWorkflow;
+  },
+): Promise<void> {
+  const { context, enabled, sites, workflow } = args;
+  if (!workflow.authProfileName || workflow.authProfileRefresh !== true) {
+    return;
+  }
+  if (!enabled) return;
+  if (sites.length === 0) {
+    console.warn(
+      `Auth profile refresh skipped for "${workflow.authProfileName}": workflow did not visit any http(s) sites.`,
+    );
+    return;
+  }
+  const existing = readProfile(workflow.authProfileName);
+  const latest = await context.storageState({ indexedDB: true });
+  const state = mergeAuthProfileStorageState(existing, latest, sites);
+  await writeProfile(workflow.authProfileName, state);
+  console.warn(`Auth profile refreshed: ${workflow.authProfileName}`);
+}
+
+function createVisitedSiteTracker(context: BrowserContext): {
+  sites: () => string[];
+  dispose: () => void;
+} {
+  const sites = new Set<string>();
+  const pageListeners = new Map<Page, (frame: Frame) => void>();
+
+  const recordUrl = (url: string): void => {
+    if (!url.startsWith("http://") && !url.startsWith("https://")) return;
+    const site = normalizeAuthProfileSite(url);
+    if (site) sites.add(site);
+  };
+
+  const trackPage = (page: Page): void => {
+    if (pageListeners.has(page)) return;
+    recordUrl(page.url());
+
+    const onFrameNavigated = (frame: Frame): void => {
+      if (frame === page.mainFrame()) {
+        recordUrl(frame.url());
+      }
+    };
+
+    pageListeners.set(page, onFrameNavigated);
+    page.on("framenavigated", onFrameNavigated);
+  };
+
+  for (const page of context.pages()) {
+    trackPage(page);
+  }
+
+  context.on("page", trackPage);
+
+  return {
+    sites: () => [...sites],
+    dispose: () => {
+      context.off("page", trackPage);
+      for (const [page, listener] of pageListeners) {
+        page.off("framenavigated", listener);
+      }
+      pageListeners.clear();
+    },
+  };
+}
+
 function chunkToString(chunk: unknown): string {
   return Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
 }

package/src/cli/router.ts

@@ -1,13 +1,17 @@
 import { authCommands } from "./commands/auth.js";
 import { billingCommands } from "./commands/billing.js";
 import { browserCommands } from "./commands/browser.js";
+import { cloudCredentialCommands } from "./commands/cloud-credentials.js";
 import { deployCommand } from "./commands/deploy.js";
 import { executionCommands } from "./commands/execution.js";
 import { experimentsCommand } from "./commands/experiments.js";
+import { importChromeProfilesCommand } from "./commands/import-chrome-profiles.js";
+import { profileCommands } from "./commands/profiles.js";
 import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
 import { searchCommand } from "./commands/search.js";
+import { telemetryMiddleware } from "./core/telemetry.js";
 import { updateCommand } from "./commands/update.js";
 import { SimpleCLI } from "affordance";
 
@@ -19,9 +23,12 @@ export const cliRoutes = {
       deploy: deployCommand,
       auth: authCommands,
       billing: billingCommands,
+      credentials: cloudCredentialCommands,
+      profiles: profileCommands,
     },
   }),
   experiments: experimentsCommand,
+  "import-chrome-profiles": importChromeProfilesCommand,
   ...executionCommands,
   search: searchCommand,
   setup: setupCommand,
@@ -32,6 +39,7 @@ export const cliRoutes = {
 
 export function createCLIApp() {
   return SimpleCLI.define("libretto", cliRoutes, {
+    middlewares: [telemetryMiddleware],
     appendHelpText: [
       "Options:",
       "  --session <name>  Required for session-scoped commands",

package/src/index.ts

@@ -112,6 +112,10 @@ export {
 } from "./shared/run/api.js";
 
 // Workflow helpers
+export {
+  librettoAuthenticate,
+  type LibrettoAuthenticateOptions,
+} from "./shared/workflow/authenticate.js";
 export {
   getDefaultWorkflowFromModuleExports,
   getWorkflowFromModuleExports,
@@ -128,6 +132,12 @@ export {
   type LibrettoWorkflowOptions,
   type WorkflowInputValidator,
 } from "./shared/workflow/workflow.js";
+export {
+  captureAuthProfileStorageState,
+  normalizeAuthProfileSite,
+  parseAuthProfileSites,
+  type AuthProfileStorageState,
+} from "./shared/workflow/auth-profile-state.js";
 const isDirectExecution = (): boolean => {
   const entryArg = process.argv[1];
   if (!entryArg) {

package/src/shared/workflow/auth-profile-name.ts

@@ -0,0 +1,27 @@
+export function normalizeProfileName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error("Profile name is required.");
+  }
+  if (!isValidProfileName(trimmed)) {
+    throw new Error(
+      `Invalid profile name "${name}". Use letters, numbers, dots, underscores, and dashes only.`,
+    );
+  }
+  return trimmed;
+}
+
+function isValidProfileName(name: string): boolean {
+  if (name === "." || name === "..") return false;
+  for (let index = 0; index < name.length; index += 1) {
+    const code = name.charCodeAt(index);
+    const isUppercase = code >= 65 && code <= 90;
+    const isLowercase = code >= 97 && code <= 122;
+    const isDigit = code >= 48 && code <= 57;
+    const isAllowedPunctuation = code === 45 || code === 46 || code === 95;
+    if (!isUppercase && !isLowercase && !isDigit && !isAllowedPunctuation) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/shared/workflow/auth-profile-state.ts

@@ -0,0 +1,144 @@
+import type { BrowserContext } from "playwright";
+
+export type AuthProfileStorageState = {
+  sites?: string[];
+  cookies?: unknown[];
+  origins?: Array<{
+    origin: string;
+    localStorage: Array<{ name: string; value: string }>;
+    indexedDB?: unknown;
+  }>;
+};
+
+export function parseAuthProfileSites(value: string): string[] {
+  const sites = value
+    .split(",")
+    .map((entry) => normalizeAuthProfileSite(entry))
+    .filter((entry): entry is string => Boolean(entry));
+  return [...new Set(sites)];
+}
+
+export function normalizeAuthProfileSite(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  try {
+    const url = trimmed.includes("://")
+      ? new URL(trimmed)
+      : new URL(`https://${trimmed}`);
+    return normalizeHost(url.hostname);
+  } catch {
+    const normalized = normalizeHost(trimmed);
+    return normalized || null;
+  }
+}
+
+export async function captureAuthProfileStorageState(
+  context: BrowserContext,
+  sites: readonly string[],
+): Promise<AuthProfileStorageState> {
+  const normalizedSites = [...new Set(
+    sites
+      .map((site) => normalizeAuthProfileSite(site))
+      .filter((site): site is string => Boolean(site)),
+  )];
+  if (normalizedSites.length === 0) {
+    throw new Error("At least one auth profile site is required.");
+  }
+
+  const state = await context.storageState({ indexedDB: true });
+  return {
+    sites: normalizedSites,
+    cookies: state.cookies.filter((cookie) =>
+      cookieDomainMatchesSites(cookie.domain, normalizedSites),
+    ),
+    origins: state.origins.filter((origin) =>
+      originMatchesSites(origin.origin, normalizedSites),
+    ),
+  };
+}
+
+export function mergeAuthProfileStorageState(
+  existing: AuthProfileStorageState,
+  latest: AuthProfileStorageState,
+  sites: readonly string[],
+): AuthProfileStorageState {
+  const normalizedSites = [...new Set(
+    sites
+      .map((site) => normalizeAuthProfileSite(site))
+      .filter((site): site is string => Boolean(site)),
+  )];
+  if (normalizedSites.length === 0) {
+    return existing;
+  }
+
+  const existingCookies = existing.cookies ?? [];
+  const latestCookies = latest.cookies ?? [];
+  const existingOrigins = existing.origins ?? [];
+  const latestOrigins = latest.origins ?? [];
+
+  const mergedSites = [
+    ...new Set([
+      ...(existing.sites ?? []),
+      ...normalizedSites,
+    ]),
+  ];
+
+  return {
+    ...existing,
+    sites: mergedSites,
+    cookies: [
+      ...existingCookies.filter(
+        (cookie) => !cookieMatchesSites(cookie, normalizedSites),
+      ),
+      ...latestCookies.filter((cookie) =>
+        cookieMatchesSites(cookie, normalizedSites),
+      ),
+    ],
+    origins: [
+      ...existingOrigins.filter(
+        (origin) => !originMatchesSites(origin.origin, normalizedSites),
+      ),
+      ...latestOrigins.filter((origin) =>
+        originMatchesSites(origin.origin, normalizedSites),
+      ),
+    ],
+  };
+}
+
+function normalizeHost(value: string): string {
+  let host = value.trim().toLowerCase();
+  while (host.startsWith(".")) host = host.slice(1);
+  while (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
+
+function cookieMatchesSites(cookie: unknown, sites: readonly string[]): boolean {
+  if (!cookie || typeof cookie !== "object" || !("domain" in cookie)) {
+    return false;
+  }
+  const domain = (cookie as { domain?: unknown }).domain;
+  return typeof domain === "string" && cookieDomainMatchesSites(domain, sites);
+}
+
+function cookieDomainMatchesSites(
+  cookieDomain: string,
+  sites: readonly string[],
+): boolean {
+  const domain = normalizeHost(cookieDomain);
+  if (!domain) return false;
+  return sites.some(
+    (site) =>
+      domain === site ||
+      domain.endsWith(`.${site}`) ||
+      site.endsWith(`.${domain}`),
+  );
+}
+
+function originMatchesSites(origin: string, sites: readonly string[]): boolean {
+  try {
+    const host = normalizeHost(new URL(origin).hostname);
+    return sites.some((site) => host === site || host.endsWith(`.${site}`));
+  } catch {
+    return false;
+  }
+}

package/src/shared/workflow/authenticate.ts

@@ -0,0 +1,63 @@
+import type { LibrettoWorkflowContext } from "./workflow.js";
+
+export type LibrettoAuthenticateOptions = {
+  validate: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
+  fallback: (
+    ctx: LibrettoWorkflowContext,
+    credentials: Record<string, string>,
+  ) => Promise<void> | void;
+  credentials?: Record<string, unknown>;
+  envPrefix?: string;
+};
+
+export async function librettoAuthenticate(
+  ctx: LibrettoWorkflowContext,
+  options: LibrettoAuthenticateOptions,
+): Promise<{ usedProfile: boolean }> {
+  if (await options.validate(ctx)) {
+    return { usedProfile: true };
+  }
+
+  const credentials = normalizeCredentials(
+    options.credentials ?? readCredentialsFromEnv(options.envPrefix),
+  );
+  await options.fallback(ctx, credentials);
+
+  if (!(await options.validate(ctx))) {
+    throw new Error("Authentication fallback completed, but validation still failed.");
+  }
+
+  return { usedProfile: false };
+}
+
+function normalizeCredentials(
+  credentials: Record<string, unknown>,
+): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(credentials)) {
+    if (typeof value === "string") normalized[key] = value;
+  }
+  return normalized;
+}
+
+function readCredentialsFromEnv(envPrefix = "LIBRETTO_"): Record<string, string> {
+  const credentials: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(envPrefix) && value !== undefined) {
+      const credentialName = key.slice(envPrefix.length).toLowerCase();
+      if (isLibrettoControlCredential(envPrefix, credentialName)) continue;
+      credentials[credentialName] = value;
+    }
+  }
+  return credentials;
+}
+
+function isLibrettoControlCredential(
+  envPrefix: string,
+  credentialName: string,
+): boolean {
+  return (
+    envPrefix === "LIBRETTO_" &&
+    ["api_key", "api_url", "timeout_seconds"].includes(credentialName)
+  );
+}

package/src/shared/workflow/credentials.ts

@@ -0,0 +1,91 @@
+function asStringMap(value: unknown): Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (typeof rawValue === "string") result[key] = rawValue;
+  }
+  return result;
+}
+
+function readHostedCredentials(input: unknown): Record<string, string> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return {};
+  }
+
+  const record = input as Record<string, unknown>;
+  return asStringMap(record.credentials);
+}
+
+export function readCredentialInputsFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const credentials: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.startsWith("LIBRETTO_CLOUD_") || value === undefined) continue;
+    if (value.trim().length === 0) continue;
+    const name = key.slice("LIBRETTO_CLOUD_".length).toLowerCase();
+    if (!name || name === "api_key") continue;
+    credentials[name] = value;
+  }
+  return credentials;
+}
+
+export function normalizeCredentialNames(
+  names: readonly string[] | undefined,
+): string[] {
+  if (!names) return [];
+  const normalized = new Set<string>();
+  for (const name of names) {
+    const value = name.trim().toLowerCase();
+    if (value.length > 0) normalized.add(value);
+  }
+  return [...normalized];
+}
+
+function filterCredentialMap(
+  credentials: Record<string, string>,
+  names: readonly string[],
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const name of names) {
+    if (credentials[name] !== undefined) result[name] = credentials[name];
+  }
+  return result;
+}
+
+function shouldReadCredentialInputsFromEnv(env: NodeJS.ProcessEnv): boolean {
+  return (env.LIBRETTO_HOSTED_RUNTIME?.trim().length ?? 0) === 0;
+}
+
+export function mergeCredentialsIntoInput(
+  input: unknown,
+  credentialNames?: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): unknown {
+  const normalizedNames = normalizeCredentialNames(credentialNames);
+  if (normalizedNames.length === 0) return input;
+
+  const existingCredentials = readHostedCredentials(input);
+  const envCredentials = shouldReadCredentialInputsFromEnv(env)
+    ? readCredentialInputsFromEnv(env)
+    : {};
+  const mergedCredentials = {
+    ...filterCredentialMap(envCredentials, normalizedNames),
+    ...filterCredentialMap(existingCredentials, normalizedNames),
+  };
+
+  if (Object.keys(mergedCredentials).length === 0) return input;
+
+  const base =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? { ...(input as Record<string, unknown>) }
+      : {};
+
+  return {
+    ...base,
+    credentials: mergedCredentials,
+  };
+}

package/src/shared/workflow/workflow.ts

@@ -4,6 +4,11 @@ import {
   createRecoveryPage,
   type RecoveryAction,
 } from "../../runtime/recovery/page-fallbacks.js";
+import { normalizeProfileName } from "./auth-profile-name.js";
+import {
+  mergeCredentialsIntoInput,
+  normalizeCredentialNames,
+} from "./credentials.js";
 
 export const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
 
@@ -17,12 +22,21 @@ export type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (
   input: Input,
 ) => Promise<Output>;
 
+export type LibrettoWorkflowAuthProfile =
+  | string
+  | {
+      name: string;
+      refresh?: boolean;
+    };
+
 export type LibrettoWorkflowDefinition<
   InputSchema extends z.ZodType = z.ZodType<unknown>,
   OutputSchema extends z.ZodType = z.ZodType<unknown>,
 > = {
   input?: InputSchema;
   output?: OutputSchema;
+  credentials?: readonly string[];
+  authProfile?: LibrettoWorkflowAuthProfile;
   recoveryAction?: RecoveryAction;
 };
 
@@ -72,10 +86,44 @@ function parseWorkflowInput<InputSchema extends z.ZodType>(
   if (!inputSchema) return input as z.infer<InputSchema>;
 
   const result = inputSchema.safeParse(input);
-  if (!result.success) {
-    throw new LibrettoWorkflowInputError(workflowName, result.error);
+  if (result.success) {
+    return reattachCredentialInput(result.data, input) as z.infer<InputSchema>;
+  }
+
+  const stripped = stripCredentialInput(input);
+  if (stripped !== input) {
+    const strippedResult = inputSchema.safeParse(stripped);
+    if (strippedResult.success) {
+      return reattachCredentialInput(strippedResult.data, input) as z.infer<InputSchema>;
+    }
   }
-  return result.data;
+
+  throw new LibrettoWorkflowInputError(workflowName, result.error);
+}
+
+function stripCredentialInput(input: unknown): unknown {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+  const { credentials: _credentials, ...rest } = input as Record<string, unknown>;
+  if (!("credentials" in (input as Record<string, unknown>))) return input;
+  return rest;
+}
+
+function reattachCredentialInput(parsed: unknown, raw: unknown): unknown {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return parsed;
+  const rawRecord = raw as Record<string, unknown>;
+  const rawCredentials =
+    rawRecord.credentials && typeof rawRecord.credentials === "object"
+      ? rawRecord.credentials
+      : undefined;
+  if (!rawCredentials) return parsed;
+  const parsedRecord =
+    parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { ...(parsed as Record<string, unknown>) }
+      : {};
+  return {
+    ...parsedRecord,
+    credentials: rawCredentials,
+  };
 }
 
 export type WorkflowInputValidator = {
@@ -104,6 +152,9 @@ export class LibrettoWorkflow<
   // this schema to JSON Schema at build time and exposes it via
   // /v1/workflows/get so API consumers know the workflow's output shape.
   public readonly outputSchema?: OutputSchema;
+  public readonly credentialNames: readonly string[];
+  public readonly authProfileName?: string;
+  public readonly authProfileRefresh?: boolean;
   public readonly recoveryAction?: RecoveryAction;
   private readonly handler: LibrettoWorkflowHandler<
     z.infer<InputSchema>,
@@ -116,6 +167,9 @@ export class LibrettoWorkflow<
       | {
           inputSchema?: InputSchema;
           outputSchema?: OutputSchema;
+          credentialNames?: readonly string[];
+          authProfileName?: string;
+          authProfileRefresh?: boolean;
           recoveryAction?: RecoveryAction;
         }
       | undefined,
@@ -127,6 +181,9 @@ export class LibrettoWorkflow<
     this.name = name;
     this.inputSchema = options?.inputSchema;
     this.outputSchema = options?.outputSchema;
+    this.credentialNames = options?.credentialNames ?? [];
+    this.authProfileName = options?.authProfileName;
+    this.authProfileRefresh = options?.authProfileRefresh;
     this.recoveryAction = options?.recoveryAction;
     this.handler = handler;
   }
@@ -135,7 +192,11 @@ export class LibrettoWorkflow<
     ctx: LibrettoWorkflowContext,
     input: unknown,
   ): Promise<z.infer<OutputSchema>> {
-    const parsed = parseWorkflowInput(this.name, this.inputSchema, input);
+    const parsed = parseWorkflowInput(
+      this.name,
+      this.inputSchema,
+      mergeCredentialsIntoInput(input, this.credentialNames),
+    );
     const workflowContext =
       !this.recoveryAction
         ? ctx
@@ -154,6 +215,9 @@ export type ExportedLibrettoWorkflow = {
   readonly name: string;
   readonly inputSchema?: z.ZodType;
   readonly outputSchema?: z.ZodType;
+  readonly credentialNames: readonly string[];
+  readonly authProfileName?: string;
+  readonly authProfileRefresh?: boolean;
   readonly recoveryAction?: RecoveryAction;
   run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
@@ -255,11 +319,18 @@ function getWorkflowConstructorOptions<
 ): {
   inputSchema?: InputSchema;
   outputSchema?: OutputSchema;
+  credentialNames: readonly string[];
+  authProfileName?: string;
+  authProfileRefresh?: boolean;
   recoveryAction?: RecoveryAction;
 } {
+  const authProfile = normalizeWorkflowAuthProfile(options.authProfile);
   return {
     inputSchema: options.input,
     outputSchema: options.output,
+    credentialNames: normalizeCredentialNames(options.credentials),
+    authProfileName: authProfile?.name,
+    authProfileRefresh: authProfile?.refresh,
     recoveryAction: options.recoveryAction,
   };
 }
@@ -320,3 +391,17 @@ export function workflow(
     maybeHandler,
   );
 }
+
+function normalizeWorkflowAuthProfile(
+  value: LibrettoWorkflowAuthProfile | undefined,
+): { name: string; refresh?: boolean } | undefined {
+  if (!value) return undefined;
+  if (typeof value === "string") return { name: normalizeProfileName(value) };
+  const name = normalizeProfileName(value.name);
+  return {
+    name,
+    ...(value.refresh === undefined
+      ? {}
+      : { refresh: value.refresh }),
+  };
+}