libretto 0.5.2 → 0.5.3-experimental.1

package/src/cli/workers/run-integration-runtime.ts

@@ -5,8 +5,11 @@ import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  getWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
   instrumentContext,
   launchBrowser,
+  type ExportedLibrettoWorkflow,
   type LibrettoWorkflowContext,
 } from "../../index.js";
 import type { LoggerApi } from "../../shared/logger/index.js";
@@ -25,9 +28,7 @@ import {
 import { installSessionTelemetry } from "../core/session-telemetry.js";
 import type { RunIntegrationWorkerRequest } from "./run-integration-worker-protocol.js";
 
-const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
-
-type LoadedLibrettoWorkflow = {
+type LoadedLibrettoWorkflow = ExportedLibrettoWorkflow & {
   run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
 
@@ -108,17 +109,6 @@ async function waitForFailureSessionRelease(args: {
   }
 }
 
-function isLoadedLibrettoWorkflow(
-  value: unknown,
-): value is LoadedLibrettoWorkflow {
-  if (!value || typeof value !== "object") return false;
-  const candidate = value as Record<PropertyKey, unknown>;
-  return (
-    candidate[LIBRETTO_WORKFLOW_BRAND] === true &&
-    typeof candidate.run === "function"
-  );
-}
-
 function resolveLocalAuthProfilePath(domain: string): string {
   return getProfilePath(normalizeDomain(domain));
 }
@@ -149,9 +139,9 @@ function getAbsoluteIntegrationPath(integrationPath: string): string {
   return absolutePath;
 }
 
-async function loadWorkflowExport(
+async function loadWorkflowByName(
   absolutePath: string,
-  exportName: string,
+  workflowName: string,
 ): Promise<LoadedLibrettoWorkflow> {
   let loadedModule: Record<string, unknown>;
   try {
@@ -167,42 +157,23 @@ async function loadWorkflowExport(
     );
   }
 
-  const targetExport = loadedModule[exportName];
-  if (!targetExport) {
-    const availableExports = Object.keys(loadedModule);
-    const detail =
-      availableExports.length > 0
-        ? ` Available exports: ${availableExports.join(", ")}`
-        : " The module has no exports.";
-    throw new Error(
-      `Export "${exportName}" was not found in ${absolutePath}.${detail}`,
-    );
+  const workflow = getWorkflowFromModuleExports(loadedModule, workflowName);
+  if (workflow) {
+    return workflow as LoadedLibrettoWorkflow;
   }
 
-  if (!isLoadedLibrettoWorkflow(targetExport)) {
-    throw new Error(
-      [
-        `Export "${exportName}" in ${absolutePath} is not a valid Libretto workflow.`,
-        "",
-        'A workflow must be created using the workflow() function from "libretto":',
-        "",
-        '  import { workflow } from "libretto";',
-        "",
-        `  export const ${exportName} = workflow<InputType, OutputType>(`,
-        "    async (ctx, input) => {",
-        "      // ctx.session  — libretto session name",
-        "      // ctx.page     — Playwright Page instance",
-        "      // ctx.logger   — MinimalLogger",
-        "      // ctx.services — injected dependencies (generic, default {})",
-        "      // input        — JSON-serializable input matching InputType",
-        "      return output; // must match OutputType",
-        "    },",
-        "  );",
-      ].join("\n"),
-    );
-  }
+  const availableWorkflows = getWorkflowsFromModuleExports(loadedModule).map(
+    (candidate) => candidate.name,
+  );
+
+  const detail =
+    availableWorkflows.length > 0
+      ? ` Available workflows: ${availableWorkflows.join(", ")}`
+      : ' No workflows found in this file. Export a workflow() instance from "libretto" directly or via `export const workflows = { ... }`.';
 
-  return targetExport;
+  throw new Error(
+    `Workflow "${workflowName}" not found in ${absolutePath}.${detail}`,
+  );
 }
 
 export async function installHeadedWorkflowVisualization(args: {
@@ -224,7 +195,7 @@ async function runIntegrationInternal(
 ): Promise<RunIntegrationOutcome> {
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
-  const workflow = await loadWorkflowExport(absolutePath, args.exportName);
+  const workflow = await loadWorkflowByName(absolutePath, args.workflowName);
   const signalPaths = getPauseSignalPaths(args.session);
   await removeSignalIfExists(signalPaths.pausedSignalPath);
   await removeSignalIfExists(signalPaths.resumeSignalPath);
@@ -233,12 +204,12 @@ async function runIntegrationInternal(
   const restoreStdout = mirrorStdoutToFile(signalPaths.outputSignalPath);
 
   console.log(
-    `Running integration "${args.exportName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
+    `Running workflow "${args.workflowName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
   );
 
   const integrationLogger = logger.withScope("integration-run", {
     integrationPath: absolutePath,
-    integrationExport: args.exportName,
+    workflowName: args.workflowName,
     session: args.session,
   });
 
@@ -287,6 +258,7 @@ async function runIntegrationInternal(
     logger: integrationLogger,
     page: browserSession.page,
     services: {},
+    credentials: args.credentials,
   };
 
   try {

package/src/cli/workers/run-integration-worker-protocol.ts

@@ -2,9 +2,10 @@ import { z } from "zod";
 
 export const RunIntegrationWorkerRequestSchema = z.object({
   integrationPath: z.string().min(1),
-  exportName: z.string().min(1),
+  workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
+  credentials: z.record(z.string(), z.unknown()).optional(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),

package/src/index.ts

@@ -102,9 +102,13 @@ export {
 
 // Workflow helpers
 export {
+  getWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
+  isLibrettoWorkflow,
   LibrettoWorkflow,
   LIBRETTO_WORKFLOW_BRAND,
   workflow,
+  type ExportedLibrettoWorkflow,
   type LibrettoWorkflowContext,
   type LibrettoWorkflowHandler,
 } from "./shared/workflow/workflow.js";

package/src/shared/workflow/workflow.ts

@@ -8,6 +8,7 @@ export type LibrettoWorkflowContext<S = {}> = {
   page: Page;
   logger: MinimalLogger;
   services: S;
+  credentials?: Record<string, unknown>;
 };
 
 export type LibrettoWorkflowHandler<
@@ -18,9 +19,14 @@ export type LibrettoWorkflowHandler<
 
 export class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
   public readonly [LIBRETTO_WORKFLOW_BRAND] = true;
+  public readonly name: string;
   private readonly handler: LibrettoWorkflowHandler<Input, Output, S>;
 
-  constructor(handler: LibrettoWorkflowHandler<Input, Output, S>) {
+  constructor(
+    name: string,
+    handler: LibrettoWorkflowHandler<Input, Output, S>,
+  ) {
+    this.name = name;
     this.handler = handler;
   }
 
@@ -29,8 +35,88 @@ export class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
   }
 }
 
+export type ExportedLibrettoWorkflow = {
+  readonly [LIBRETTO_WORKFLOW_BRAND]: true;
+  readonly name: string;
+  run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
+};
+
+type WorkflowModuleExports = Record<string, unknown>;
+
+// Use the workflow brand instead of `instanceof` so imported workflows are
+// still recognized after loading the integration module dynamically.
+export function isLibrettoWorkflow(
+  value: unknown,
+): value is ExportedLibrettoWorkflow {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<PropertyKey, unknown>;
+  return (
+    candidate[LIBRETTO_WORKFLOW_BRAND] === true &&
+    typeof candidate.name === "string" &&
+    typeof candidate.run === "function"
+  );
+}
+
+function addWorkflowOrThrow(
+  workflowsByName: Map<string, ExportedLibrettoWorkflow>,
+  value: unknown,
+): void {
+  if (!isLibrettoWorkflow(value)) return;
+
+  // Re-exporting the same workflow object is fine, but two distinct workflow
+  // instances cannot claim the same runtime name.
+  const existing = workflowsByName.get(value.name);
+  if (existing && existing !== value) {
+    throw new Error(
+      `Duplicate workflow name: "${value.name}". Each workflow() call must use a unique name.`,
+    );
+  }
+
+  workflowsByName.set(value.name, value);
+}
+
+export function getWorkflowsFromModuleExports(
+  moduleExports: WorkflowModuleExports,
+): ExportedLibrettoWorkflow[] {
+  const workflowsByName = new Map<string, ExportedLibrettoWorkflow>();
+
+  for (const [exportName, value] of Object.entries(moduleExports)) {
+    if (exportName === "workflows" && value && typeof value === "object") {
+      // Support both `export const workflows = workflow(...)` and
+      // `export const workflows = { myWorkflow }`.
+      if (isLibrettoWorkflow(value)) {
+        addWorkflowOrThrow(workflowsByName, value);
+      } else {
+        for (const nestedValue of Object.values(
+          value as Record<string, unknown>,
+        )) {
+          addWorkflowOrThrow(workflowsByName, nestedValue);
+        }
+      }
+      continue;
+    }
+
+    addWorkflowOrThrow(workflowsByName, value);
+  }
+
+  return [...workflowsByName.values()];
+}
+
+export function getWorkflowFromModuleExports(
+  moduleExports: WorkflowModuleExports,
+  workflowName: string,
+): ExportedLibrettoWorkflow | null {
+  for (const workflow of getWorkflowsFromModuleExports(moduleExports)) {
+    if (workflow.name === workflowName) {
+      return workflow;
+    }
+  }
+  return null;
+}
+
 export function workflow<Input = unknown, Output = unknown, S = {}>(
+  name: string,
   handler: LibrettoWorkflowHandler<Input, Output, S>,
 ): LibrettoWorkflow<Input, Output, S> {
-  return new LibrettoWorkflow(handler);
+  return new LibrettoWorkflow(name, handler);
 }

package/scripts/prepare-release.sh

@@ -1,97 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage: scripts/prepare-release.sh [patch|minor|major]
-
-Creates a release PR branch from main, bumps package.json, pushes the branch,
-and opens a pull request targeting main.
-EOF
-}
-
-bump="${1:-patch}"
-
-case "$bump" in
-  patch|minor|major)
-    ;;
-  -h|--help|help)
-    usage
-    exit 0
-    ;;
-  *)
-    echo "Invalid bump type: $bump" >&2
-    usage >&2
-    exit 1
-    ;;
-esac
-
-if ! command -v gh >/dev/null 2>&1; then
-  echo "gh CLI is required." >&2
-  exit 1
-fi
-
-if [ -n "$(git status --porcelain)" ]; then
-  echo "Working tree must be clean before preparing a release." >&2
-  exit 1
-fi
-
-current_branch="$(git branch --show-current)"
-if [ "$current_branch" != "main" ]; then
-  echo "Switching from $current_branch to main."
-fi
-
-git fetch origin
-git checkout main
-git pull --ff-only origin main
-
-pnpm install --frozen-lockfile
-pnpm type-check
-pnpm test
-
-current_version="$(node -p "require('./package.json').version")"
-next_version="$(node -e '
-const [major, minor, patch] = process.argv[1].split(".").map(Number)
-const bump = process.argv[2]
-
-let next
-if (bump === "major") next = [major + 1, 0, 0]
-else if (bump === "minor") next = [major, minor + 1, 0]
-else next = [major, minor, patch + 1]
-
-process.stdout.write(next.join("."))
-' "$current_version" "$bump")"
-branch_name="tk-release-v${next_version}"
-
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  echo "Local branch ${branch_name} already exists." >&2
-  exit 1
-fi
-
-if git ls-remote --exit-code --heads origin "${branch_name}" >/dev/null 2>&1; then
-  echo "Remote branch ${branch_name} already exists." >&2
-  exit 1
-fi
-
-npm version "$next_version" --no-git-tag-version >/dev/null
-
-git checkout -b "$branch_name"
-git add package.json
-git commit -m "release: v${next_version}"
-git push -u origin "$branch_name"
-
-gh pr create \
-  --base main \
-  --head "$branch_name" \
-  --title "release: v${next_version}" \
-  --body "$(cat <<EOF
-## Summary
-
-- release libretto v${next_version}
-
-## Verification
-
-- pnpm type-check
-- pnpm test
-EOF
-)"