libretto 0.5.2 → 0.5.3-experimental.1

package/scripts/generate-changelog.ts

@@ -0,0 +1,132 @@
+import { execFileSync } from "node:child_process";
+import { Agent, type AgentTool, type AgentEvent } from "@mariozechner/pi-agent-core";
+import { getModel } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+
+const tag = process.argv[2];
+if (!tag) {
+  console.error("Usage: generate-changelog.ts <tag>");
+  console.error("Example: generate-changelog.ts v0.5.2");
+  process.exit(1);
+}
+
+if (!process.env.ANTHROPIC_API_KEY) {
+  console.error("ANTHROPIC_API_KEY is required.");
+  process.exit(1);
+}
+
+const ALLOWED_GH_SUBCOMMANDS = new Set(["pr", "release", "repo", "issue"]);
+const ALLOWED_ACTIONS = new Set(["list", "view", "diff", "status", "checks"]);
+
+const ghTool: AgentTool = {
+  name: "gh",
+  label: "GitHub CLI",
+  description: [
+    "Run a read-only GitHub CLI command. The arguments are passed directly to `gh`.",
+    "Examples: 'release list --limit 5', 'pr list --state merged --json number,title',",
+    "'pr view 128 --json title,body,files', 'pr diff 128'.",
+    "Only read operations are allowed (list, view, diff, etc.). Mutating commands will be rejected.",
+  ].join(" "),
+  parameters: Type.Object({
+    args: Type.String({ description: "Arguments to pass to gh (without the leading 'gh')" }),
+  }),
+  execute: async (_toolCallId, rawParams) => {
+    const params = rawParams as { args: string };
+    const args = params.args.trim();
+    const parts = args.split(/\s+/);
+    const subcommand = parts[0];
+
+    if (!subcommand || !ALLOWED_GH_SUBCOMMANDS.has(subcommand)) {
+      throw new Error(`Subcommand '${subcommand}' is not allowed. Allowed: ${[...ALLOWED_GH_SUBCOMMANDS].join(", ")}`);
+    }
+
+    const action = parts[1];
+    if (!action || !ALLOWED_ACTIONS.has(action)) {
+      throw new Error(`Action '${action}' is not allowed. Allowed: ${[...ALLOWED_ACTIONS].join(", ")}`);
+    }
+
+    try {
+      const output = execFileSync("gh", parts, {
+        encoding: "utf8",
+        timeout: 300_000,
+        maxBuffer: 1024 * 1024,
+      });
+      return { content: [{ type: "text", text: output }], details: {} };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`gh command failed: ${message}`);
+    }
+  },
+};
+
+const agent = new Agent({
+  initialState: {
+    systemPrompt: [
+      `Generate release notes for the ${tag} release of Libretto.`,
+      "",
+      "Use the gh tool to explore what changed since the previous release.",
+      "Useful queries:",
+      "- 'release list --limit 5' to find the previous release tag",
+      "- 'pr list --state merged --limit 50 --json number,title,body,labels' to find merged PRs",
+      "- 'pr diff NUMBER' to see the full diff of a PR (base to head, not individual commits)",
+      "- 'pr view NUMBER --json title,body,files' to see PR details",
+      "",
+      "IMPORTANT: Always read the full PR diff to understand what actually changed.",
+      "Do NOT rely solely on PR titles and descriptions — they may be incomplete or misleading.",
+      "The diff is the source of truth for what the release note should say.",
+      "",
+      "Guidelines:",
+      "- Write concise, user-facing release notes in markdown.",
+      "- Group changes into sections like Features, Fixes, and Improvements. Only include sections that have entries.",
+      "- Focus on what changed from the user's perspective, not internal implementation details.",
+      "- Do NOT include PR numbers or links.",
+      "- Skip PRs labeled 'skip-changelog'.",
+      "- Your response must contain ONLY the raw markdown release notes. No preamble like 'Here are the release notes'. No commentary or explanation. No '---' separators. The very first character of your response must be '#'. Example format:",
+      "",
+      "## Features",
+      "",
+      "- **Thing**: Description",
+    ].join("\n"),
+    model: getModel("anthropic", "claude-sonnet-4-6"),
+    tools: [ghTool],
+  },
+});
+
+let finalText = "";
+
+agent.subscribe((event: AgentEvent) => {
+  if (event.type === "agent_end") {
+    const messages = event.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant" && Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (typeof block === "object" && "type" in block && block.type === "text" && "text" in block) {
+            finalText = block.text as string;
+            return;
+          }
+        }
+      }
+    }
+  }
+});
+
+await agent.prompt("Generate the release notes now.");
+
+if (!finalText) {
+  console.error("Changelog generation failed: no text output from agent.");
+  process.exit(1);
+}
+
+// Strip any preamble before the first markdown heading.
+const headingIndex = finalText.indexOf("\n#");
+if (headingIndex >= 0) {
+  finalText = finalText.slice(headingIndex + 1);
+} else if (finalText.startsWith("#")) {
+  // Already starts with a heading, keep as-is.
+} else {
+  console.error("Changelog generation failed: output does not contain markdown headings.");
+  process.exit(1);
+}
+
+process.stdout.write(finalText);

package/scripts/skills-libretto.mjs

@@ -11,7 +11,7 @@ import {
 import { relative, resolve, join } from "node:path";
 
 export const SKILL_DIRS = [
-  "skills/libretto",
+  "packages/libretto/skills/libretto",
   ".agents/skills/libretto",
   ".claude/skills/libretto",
 ];

package/scripts/sync-skills.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { SKILL_DIRS, syncRepoSkills } from "./skills-libretto.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(__dirname, "..");
+const repoRoot = join(__dirname, "..", "..", "..");
 
 syncRepoSkills(repoRoot);
 console.log(`libretto: synced skill mirrors across ${SKILL_DIRS.join(", ")}`);

package/skills/libretto/SKILL.md

@@ -83,6 +83,7 @@ npx libretto snapshot \
 
 - Use `exec` for focused inspection and short-lived interaction experiments.
 - Use `exec` to validate selectors, inspect data, or prototype a step before you encode it in the workflow file.
+- Use `exec -` to run multi-line scripts from stdin, especially when the code is too long or complex for a command line argument.
 - Available globals: `page`, `context`, `browser`, `state`, `fetch`, `Buffer`.
 - Let failures throw. Do not hide `exec` failures with `try/catch` or `.catch()`.
 - Do not run multiple `exec` commands in parallel.
@@ -91,6 +92,7 @@ npx libretto snapshot \
 npx libretto exec "return await page.url()"
 npx libretto exec "return await page.locator('button').count()"
 npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
+echo "return await page.url()" | npx libretto exec - --session debug-example
 ```
 
 ### `pages`
@@ -113,8 +115,8 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```bash
-npx libretto run ./integration.ts main --headless --params '{"status":"open"}'
-npx libretto run ./integration.ts main --auth-profile app.example.com
+npx libretto run ./integration.ts workflowName --headless --params '{"status":"open"}'
+npx libretto run ./integration.ts workflowName --auth-profile app.example.com
 ```
 
 ### `resume`

package/skills/libretto/references/code-generation-rules.md

@@ -6,7 +6,7 @@ Follow the user's existing codebase conventions, abstractions, and patterns when
 
 ## Workflow File Structure
 
-Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <exportName>`. Import `workflow` and its types from `"libretto"`:
+Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <workflowName>`. Import `workflow` and its types from `"libretto"`:
 
 ```typescript
 import { workflow, pause, type LibrettoWorkflowContext } from "libretto";
@@ -23,7 +23,8 @@ type Output = {
 };
 
 export const myWorkflow = workflow<Input, Output>(
-  async (ctx, input): Promise<Output> => {
+  "myWorkflow",
+  async (ctx: LibrettoWorkflowContext, input): Promise<Output> => {
     const { session, page, logger } = ctx;
 
     logger.info("workflow-start", { session, query: input.query });
@@ -37,8 +38,8 @@ export const myWorkflow = workflow<Input, Output>(
 
 Key points:
 
-- The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
-- `workflow(handler)` returns a branded workflow object with a `.run(ctx, input)` method. The CLI expects that contract.
+- `workflow(name, handler)` takes a unique workflow name and returns the workflow object that Libretto can run.
+- `npx libretto run ./file.ts myWorkflow` resolves `myWorkflow` from the workflows exported by `./file.ts`, so export or re-export the workflow from that file directly or through a `workflows` object, and make sure the run argument matches the name passed to `workflow("myWorkflow", ...)`.
 - `ctx` provides `session`, `page`, `logger`, and `services` (generic, default `{}`)
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.
@@ -57,6 +58,7 @@ import { type Transaction } from "./db";
 type MyServices = { tx?: Transaction };
 
 export const myWorkflow = workflow<Input, Output, MyServices>(
+  "myWorkflow",
   async (ctx, input) => {
     if (ctx.services.tx) {
       await ctx.services.tx.insert(/* ... */);

package/src/cli/commands/deploy.ts

@@ -0,0 +1,209 @@
+import { execSync } from "node:child_process";
+import {
+  cpSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { SimpleCLI } from "../framework/simple-cli.js";
+
+type DeploymentStatus = "building" | "ready" | "failed";
+
+type DeploymentResponse = {
+  json: {
+    deployment_id: string;
+    name: string;
+    version: number;
+    status: DeploymentStatus;
+    workflows?: string[] | null;
+    build_error?: string | null;
+  };
+};
+
+function getConfig() {
+  const apiUrl = process.env.LIBRETTO_API_URL;
+  const apiKey = process.env.LIBRETTO_API_KEY;
+
+  if (!apiUrl) {
+    throw new Error(
+      "LIBRETTO_API_URL environment variable is required.",
+    );
+  }
+  if (!apiKey) {
+    throw new Error(
+      "LIBRETTO_API_KEY environment variable is required.",
+    );
+  }
+
+  return { apiUrl: apiUrl.replace(/\/$/, ""), apiKey };
+}
+
+async function postJson(
+  apiUrl: string,
+  apiKey: string,
+  path: string,
+  input: Record<string, unknown> = {},
+): Promise<Response> {
+  return fetch(`${apiUrl}${path}`, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ json: input }),
+  });
+}
+
+function buildSourceTarball(sourceDir: string): string {
+  const absSourceDir = resolve(sourceDir);
+
+  const pkgJsonPath = join(absSourceDir, "package.json");
+  try {
+    readFileSync(pkgJsonPath, "utf8");
+  } catch {
+    throw new Error(
+      `No package.json found in ${absSourceDir}. Deploy source must contain a package.json.`,
+    );
+  }
+
+  const dir = join(tmpdir(), `libretto-deploy-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+
+  cpSync(absSourceDir, dir, { recursive: true });
+
+  const tarPath = join(dir, "source.tar.gz");
+  execSync(
+    `tar czf "${tarPath}" --exclude=source.tar.gz --exclude=node_modules --exclude=.git -C "${dir}" .`,
+  );
+  return readFileSync(tarPath).toString("base64");
+}
+
+async function pollDeployment(
+  apiUrl: string,
+  apiKey: string,
+  deploymentId: string,
+  pollIntervalMs: number,
+  maxWaitMs: number,
+): Promise<DeploymentResponse["json"]> {
+  const start = Date.now();
+  let status: DeploymentStatus = "building";
+  let deployment: DeploymentResponse["json"] | undefined;
+
+  while (status === "building" && Date.now() - start < maxWaitMs) {
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+
+    const res = await postJson(apiUrl, apiKey, "/v1/deployments/get", {
+      id: deploymentId,
+    });
+    const body = (await res.json()) as DeploymentResponse;
+    if (res.status !== 200) {
+      throw new Error(
+        `Failed to get deployment status (${res.status}): ${JSON.stringify(body)}`,
+      );
+    }
+    status = body.json.status;
+    deployment = body.json;
+    process.stdout.write(".");
+  }
+  console.log();
+
+  if (!deployment) {
+    throw new Error("Deployment timed out before receiving a status update.");
+  }
+
+  return deployment;
+}
+
+export const deployInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("sourceDir", z.string().default("."), {
+      help: "Path to source directory (default: current directory)",
+    }),
+  ],
+  named: {
+    name: SimpleCLI.option(z.string(), {
+      help: "Deployment name",
+    }),
+    description: SimpleCLI.option(z.string().optional(), {
+      help: "Deployment description",
+    }),
+    entryPoint: SimpleCLI.option(z.string().optional(), {
+      name: "entry-point",
+      help: "Entry point file (default: index.ts)",
+    }),
+  },
+});
+
+export const deployCommand = SimpleCLI.command({
+  description: "[experimental] Deploy workflows to the hosted platform",
+  experimental: true,
+})
+  .input(deployInput)
+  .handle(async ({ input }) => {
+    const { apiUrl, apiKey } = getConfig();
+
+    console.log(`Packaging source from ${resolve(input.sourceDir)}...`);
+    const source = buildSourceTarball(input.sourceDir);
+
+    const createPayload: Record<string, unknown> = {
+      name: input.name,
+      source,
+    };
+    if (input.description) createPayload.description = input.description;
+    if (input.entryPoint) createPayload.entry_point = input.entryPoint;
+
+    console.log("Uploading deployment...");
+    const res = await postJson(
+      apiUrl,
+      apiKey,
+      "/v1/deployments/create",
+      createPayload,
+    );
+    const body = (await res.json()) as DeploymentResponse;
+    if (res.status !== 200) {
+      throw new Error(
+        `Failed to create deployment (${res.status}): ${JSON.stringify(body)}`,
+      );
+    }
+
+    const { deployment_id, name, version, status } = body.json;
+    console.log(
+      `Deployment created: ${name} v${version} (${deployment_id})`,
+    );
+    console.log(`Status: ${status}`);
+
+    if (status === "building") {
+      process.stdout.write("Waiting for build");
+      const deployment = await pollDeployment(
+        apiUrl,
+        apiKey,
+        deployment_id,
+        10_000,
+        5 * 60 * 1000,
+      );
+
+      if (deployment.status === "failed") {
+        throw new Error(
+          `Build failed: ${deployment.build_error ?? "unknown error"}`,
+        );
+      }
+
+      if (deployment.status === "ready") {
+        console.log(`Build complete.`);
+        if (deployment.workflows?.length) {
+          console.log(
+            `Workflows: ${deployment.workflows.join(", ")}`,
+          );
+        }
+      } else {
+        console.log(
+          `Build still in progress (timed out waiting). Check status with deployment ID: ${deployment_id}`,
+        );
+      }
+    }
+
+    return deployment_id;
+  });

package/src/cli/commands/execution.ts

@@ -605,9 +605,10 @@ async function runIntegrationFromFile(
   );
   const payload = JSON.stringify({
     integrationPath: args.integrationPath,
-    exportName: args.exportName,
+    workflowName: args.workflowName,
     session: args.session,
     params: args.params,
+    credentials: args.credentials,
     headless: args.headless,
     visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
@@ -656,11 +657,20 @@ async function runIntegrationFromFile(
   console.log("Integration completed.");
 }
 
+function readStdinSync(): string | null {
+  if (process.stdin.isTTY === true) return null;
+  try {
+    const content = readFileSync(0, "utf8");
+    return content.trim().length > 0 ? content : null;
+  } catch {
+    return null;
+  }
+}
+
 export const execInput = SimpleCLI.input({
   positionals: [
-    SimpleCLI.positional("codeParts", z.array(z.string()).default([]), {
+    SimpleCLI.positional("code", z.string().optional(), {
       help: "Playwright TypeScript code to execute",
-      variadic: true,
     }),
   ],
   named: {
@@ -671,8 +681,8 @@ export const execInput = SimpleCLI.input({
     page: pageOption(),
   },
 }).refine(
-  (input) => input.codeParts.length > 0,
-  `Usage: libretto exec <code> [--session <name>] [--visualize]`,
+  (input) => input.code !== undefined,
+  `Usage: libretto exec <code|-> [--session <name>] [--visualize]\n       echo '<code>' | libretto exec - [--session <name>] [--visualize]`,
 );
 
 export const execCommand = SimpleCLI.command({
@@ -681,8 +691,15 @@ export const execCommand = SimpleCLI.command({
   .input(execInput)
   .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
+    const code = input.code!;
+    const codeFromArgsOrStdin = code === "-" ? readStdinSync() : code;
+    if (codeFromArgsOrStdin === null) {
+      throw new Error(
+        "Missing stdin input for `exec -`. Pipe Playwright code into stdin.",
+      );
+    }
     await runExec(
-      input.codeParts.join(" "),
+      codeFromArgsOrStdin,
       ctx.session,
       ctx.logger,
       input.visualize,
@@ -690,15 +707,15 @@ export const execCommand = SimpleCLI.command({
     );
   });
 
-const runUsage = `Usage: libretto run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
+const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--credentials <json>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
 
 export const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {
       help: "Path to the integration file",
     }),
-    SimpleCLI.positional("integrationExport", z.string().optional(), {
-      help: "Named workflow export to run",
+    SimpleCLI.positional("workflowName", z.string().optional(), {
+      help: "Workflow name to run (from workflow(name, handler))",
     }),
   ],
   named: {
@@ -710,6 +727,9 @@ export const runInput = SimpleCLI.input({
       name: "params-file",
       help: "Path to a JSON params file",
     }),
+    credentials: SimpleCLI.option(z.string().optional(), {
+      help: "Inline JSON credentials passed to ctx.credentials",
+    }),
     tsconfig: SimpleCLI.option(z.string().optional(), {
       help: "Path to a tsconfig used for workflow module resolution",
     }),
@@ -729,7 +749,7 @@ export const runInput = SimpleCLI.input({
   },
 })
   .refine(
-    (input) => Boolean(input.integrationFile && input.integrationExport),
+    (input) => Boolean(input.integrationFile && input.workflowName),
     runUsage,
   )
   .refine(
@@ -772,6 +792,13 @@ export const runCommand = SimpleCLI.command({
     assertSessionAvailableForStart(ctx.session, ctx.logger);
 
     const params = resolveRunParams(input.params, input.paramsFile);
+    const rawCredentials = input.credentials
+      ? parseJsonArg("--credentials", input.credentials)
+      : undefined;
+    if (rawCredentials !== undefined && (typeof rawCredentials !== "object" || rawCredentials === null || Array.isArray(rawCredentials))) {
+      throw new Error("--credentials must be a JSON object (e.g., '{\"key\": \"value\"}').");
+    }
+    const credentials = rawCredentials as Record<string, unknown> | undefined;
     const headlessMode = input.headed
       ? false
       : input.headless
@@ -786,9 +813,10 @@ export const runCommand = SimpleCLI.command({
     await runIntegrationFromFile(
       {
         integrationPath: input.integrationFile!,
-        exportName: input.integrationExport!,
+        workflowName: input.workflowName!,
         session: ctx.session,
         params,
+        credentials,
         tsconfigPath: input.tsconfig,
         headless: headlessMode ?? false,
         visualize,

package/src/cli/framework/simple-cli.ts

@@ -4,6 +4,7 @@ type RecordUnknown = Record<string, unknown>;
 
 export type SimpleCLICommandConfig = {
   description: string;
+  experimental?: boolean;
 };
 
 export type SimpleCLIInputRaw = {
@@ -111,6 +112,7 @@ export type SimpleCLIResolvedCommand = {
 };
 
 type InternalResolvedCommand = SimpleCLIResolvedCommand & {
+  experimental?: boolean;
   input?: SimpleCLIInput<unknown>;
   middlewares: AnySimpleCLIMiddleware[];
   handler: SimpleCLIHandler<unknown, SimpleCLIContext, unknown>;
@@ -579,6 +581,11 @@ export class SimpleCLIApp {
         break;
       }
 
+      if (arg === "-") {
+        positionals.push(arg);
+        continue;
+      }
+
       if (arg.startsWith("--")) {
         const [rawName, inlineValue] = splitNamedArg(arg.slice(2));
         const namedEntry = namedSpecs.get(rawName);
@@ -853,6 +860,7 @@ export class SimpleCLIApp {
       }
 
       const command = this.findCommandByPath(routeEntry.path);
+      if (command?.experimental) continue;
       entries.push({
         label: token,
         description: command?.description,
@@ -1072,6 +1080,7 @@ function resolveRouteTree(
       routeKey: pathToRouteKey(path),
       path,
       description: command.config.description,
+      experimental: command.config.experimental,
       input: command.input,
       middlewares: mergeInheritedMiddlewares(
         parentMiddlewares,

package/src/cli/router.ts

@@ -1,5 +1,6 @@
 import { aiCommands } from "./commands/ai.js";
 import { browserCommands } from "./commands/browser.js";
+import { deployCommand } from "./commands/deploy.js";
 import { executionCommands } from "./commands/execution.js";
 import { initCommand } from "./commands/init.js";
 import { logCommands } from "./commands/logs.js";
@@ -13,6 +14,7 @@ export const cliRoutes = {
   ai: aiCommands,
   init: initCommand,
   snapshot: snapshotCommand,
+  deploy: deployCommand,
 };
 
 export function createCLIApp() {