libretto 0.6.31 → 0.6.33

package/src/cli/commands/cloud-credentials.ts

@@ -1,5 +1,6 @@
 import { SimpleCLI } from "affordance";
-import { orpcCall, resolveApiUrl } from "../core/auth-fetch.js";
+import { orpcCall } from "../core/auth-fetch.js";
+import { withCloudApiKey } from "./shared.js";
 
 const CLOUD_CREDENTIAL_ENV_PREFIX = "LIBRETTO_CLOUD_";
 
@@ -10,19 +11,6 @@ type UpsertCredentialResponse = {
   message: string;
 };
 
-function requireApiKeyCredential() {
-  const apiKey = process.env.LIBRETTO_API_KEY?.trim();
-  if (!apiKey) {
-    throw new Error(
-      "LIBRETTO_API_KEY is required to manage Libretto Cloud credentials. Issue one with `libretto cloud auth api-key issue --label <label>`.",
-    );
-  }
-  return {
-    apiUrl: resolveApiUrl(null),
-    credential: { source: "env-api-key" as const, apiKey },
-  };
-}
-
 function parseEnvCredentials(prefix: string): Array<{ name: string; value: string }> {
   const credentials: Record<string, string> = {};
   for (const [key, value] of Object.entries(process.env)) {
@@ -44,22 +32,22 @@ export const pushCredentialCommand = SimpleCLI.command({
     positionals: [],
     named: {},
   }))
-  .handle(async () => {
+  .use(withCloudApiKey("manage Libretto Cloud credentials"))
+  .handle(async ({ ctx }) => {
     const credentials = parseEnvCredentials(CLOUD_CREDENTIAL_ENV_PREFIX);
     if (credentials.length === 0) {
       throw new Error(
         `No non-empty env vars found with prefix ${CLOUD_CREDENTIAL_ENV_PREFIX}.`,
       );
     }
-    const { apiUrl, credential } = requireApiKeyCredential();
     let created = 0;
     let updated = 0;
     for (const item of credentials) {
       const response = await orpcCall<UpsertCredentialResponse>({
-        apiUrl,
+        apiUrl: ctx.apiUrl,
         path: "/v1/credentials/upsert",
         input: item,
-        credential,
+        credential: ctx.credential,
       });
       if (response.overwritten) {
         updated += 1;

package/src/cli/commands/cloud-jobs.ts

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { SimpleCLI } from "affordance";
+import { orpcCall } from "../core/auth-fetch.js";
+import { withCloudApiKey } from "./shared.js";
+
+type JobStatus = "queued" | "starting_browser" | "running";
+
+type CreateJobResponse = {
+  success: true;
+  job_id: string;
+  status: JobStatus;
+  message: string;
+};
+
+const createJobUsage =
+  "Usage: libretto cloud jobs create <workflow> [--params <json> | --params-file <path>]";
+
+function parseJsonObject(label: string, raw: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in ${label}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function readJsonObjectFile(
+  label: string,
+  filePath: string,
+): Record<string, unknown> {
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    throw new Error(
+      `Could not read ${label} "${filePath}". Ensure the file exists and is readable.`,
+    );
+  }
+  return parseJsonObject(label, content);
+}
+
+export const createCloudJobInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("workflow", z.string().optional(), {
+      help: "Deployed workflow name to run",
+    }),
+  ],
+  named: {
+    params: SimpleCLI.option(z.string().optional(), {
+      help: "Inline JSON params object",
+    }),
+    paramsFile: SimpleCLI.option(z.string().optional(), {
+      name: "params-file",
+      help: "Path to a JSON params file",
+    }),
+    credentialId: SimpleCLI.option(z.string().optional(), {
+      name: "credential-id",
+      help: "Stored cloud credential id to pass to the workflow",
+    }),
+    timeoutSeconds: SimpleCLI.option(z.coerce.number().int().min(1).optional(), {
+      name: "timeout-seconds",
+      help: "Job timeout in seconds",
+    }),
+    headed: SimpleCLI.flag({ help: "Run browser in headed mode" }),
+    headless: SimpleCLI.flag({ help: "Run browser in headless mode" }),
+    callbackUrl: SimpleCLI.option(z.string().optional(), {
+      name: "callback-url",
+      help: "Per-job callback URL",
+    }),
+    callbackSecret: SimpleCLI.option(z.string().optional(), {
+      name: "callback-secret",
+      help: "Secret used to sign the per-job callback",
+    }),
+    skipCallbacks: SimpleCLI.flag({
+      name: "skip-callbacks",
+      help: "Skip stored webhook callbacks for this job",
+    }),
+    residentialProxy: SimpleCLI.option(z.string().optional(), {
+      name: "residential-proxy",
+      help: "Residential proxy config as a JSON object",
+    }),
+  },
+})
+  .refine((input) => Boolean(input.workflow), createJobUsage)
+  .refine(
+    (input) => !(input.params && input.paramsFile),
+    "Pass either --params or --params-file, not both.",
+  )
+  .refine(
+    (input) => !(input.headed && input.headless),
+    "Cannot pass both --headed and --headless.",
+  )
+  .refine(
+    (input) =>
+      (!input.callbackUrl && !input.callbackSecret) ||
+      Boolean(input.callbackUrl && input.callbackSecret),
+    "Pass both --callback-url and --callback-secret, or omit both.",
+  );
+
+export const createCloudJobCommand = SimpleCLI.command({
+  description: "Create a Libretto Cloud job for a deployed workflow",
+})
+  .input(createCloudJobInput)
+  .use(withCloudApiKey("create Libretto Cloud jobs"))
+  .handle(async ({ input, ctx }) => {
+    const params = input.paramsFile
+      ? readJsonObjectFile("--params-file", input.paramsFile)
+      : input.params
+        ? parseJsonObject("--params", input.params)
+        : {};
+    const residentialProxy = input.residentialProxy
+      ? parseJsonObject("--residential-proxy", input.residentialProxy)
+      : undefined;
+
+    const payload: Record<string, unknown> = {
+      workflow: input.workflow!,
+      params,
+    };
+    if (input.credentialId) payload.credential_id = input.credentialId;
+    if (input.timeoutSeconds !== undefined) {
+      payload.timeout_seconds = input.timeoutSeconds;
+    }
+    if (input.headed) payload.headless = false;
+    if (input.headless) payload.headless = true;
+    if (input.callbackUrl) payload.callback_url = input.callbackUrl;
+    if (input.callbackSecret) payload.callback_secret = input.callbackSecret;
+    if (input.skipCallbacks) payload.skip_callbacks = true;
+    if (residentialProxy !== undefined) {
+      payload.residential_proxy = residentialProxy;
+    }
+
+    const response = await orpcCall<CreateJobResponse>({
+      apiUrl: ctx.apiUrl,
+      path: "/v1/jobs/create",
+      input: payload,
+      credential: ctx.credential,
+    });
+
+    console.log(`Job created: ${response.job_id}`);
+    console.log(`Status: ${response.status}`);
+    console.log(response.message);
+    return response.job_id;
+  });
+
+export const cloudJobCommands = SimpleCLI.group({
+  description: "Create and manage hosted jobs",
+  routes: {
+    create: createCloudJobCommand,
+  },
+});

package/src/cli/commands/cloud-schedules.ts

@@ -0,0 +1,164 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { SimpleCLI } from "affordance";
+import { orpcCall } from "../core/auth-fetch.js";
+import { withCloudApiKey } from "./shared.js";
+
+type ScheduleResponse = {
+  id: string;
+  workflow: string;
+  cron_expr: string;
+  timezone: string;
+  enabled: boolean;
+  next_fire_at: string;
+};
+
+type CreateScheduleResponse = {
+  success: true;
+  schedule: ScheduleResponse;
+};
+
+const createScheduleUsage =
+  "Usage: libretto cloud schedules create <workflow> --cron <expr> [--params <json> | --params-file <path>]";
+
+function parseJsonObject(label: string, raw: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in ${label}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function readJsonObjectFile(
+  label: string,
+  filePath: string,
+): Record<string, unknown> {
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    throw new Error(
+      `Could not read ${label} "${filePath}". Ensure the file exists and is readable.`,
+    );
+  }
+  return parseJsonObject(label, content);
+}
+
+export const createCloudScheduleInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("workflow", z.string().optional(), {
+      help: "Deployed workflow name to schedule",
+    }),
+  ],
+  named: {
+    cron: SimpleCLI.option(z.string().optional(), {
+      help: "Standard 5-field cron expression",
+    }),
+    timezone: SimpleCLI.option(z.string().optional(), {
+      help: "IANA timezone name (default: UTC)",
+    }),
+    params: SimpleCLI.option(z.string().optional(), {
+      help: "Inline JSON params object",
+    }),
+    paramsFile: SimpleCLI.option(z.string().optional(), {
+      name: "params-file",
+      help: "Path to a JSON params file",
+    }),
+    timeoutSeconds: SimpleCLI.option(z.coerce.number().int().min(1).optional(), {
+      name: "timeout-seconds",
+      help: "Job timeout in seconds for each schedule fire",
+    }),
+    callbackUrl: SimpleCLI.option(z.string().optional(), {
+      name: "callback-url",
+      help: "Per-schedule callback URL",
+    }),
+    callbackSecret: SimpleCLI.option(z.string().optional(), {
+      name: "callback-secret",
+      help: "Secret used to sign per-schedule callbacks",
+    }),
+    skipCallbacks: SimpleCLI.flag({
+      name: "skip-callbacks",
+      help: "Skip stored webhook callbacks for jobs created by this schedule",
+    }),
+    residentialProxy: SimpleCLI.option(z.string().optional(), {
+      name: "residential-proxy",
+      help: "Residential proxy config as a JSON object",
+    }),
+    disabled: SimpleCLI.flag({
+      help: "Create the schedule disabled",
+    }),
+  },
+})
+  .refine((input) => Boolean(input.workflow && input.cron), createScheduleUsage)
+  .refine(
+    (input) => !(input.params && input.paramsFile),
+    "Pass either --params or --params-file, not both.",
+  )
+  .refine(
+    (input) =>
+      (!input.callbackUrl && !input.callbackSecret) ||
+      Boolean(input.callbackUrl && input.callbackSecret),
+    "Pass both --callback-url and --callback-secret, or omit both.",
+  );
+
+export const createCloudScheduleCommand = SimpleCLI.command({
+  description: "Create a recurring schedule for a deployed workflow",
+})
+  .input(createCloudScheduleInput)
+  .use(withCloudApiKey("create Libretto Cloud schedules"))
+  .handle(async ({ input, ctx }) => {
+    const params = input.paramsFile
+      ? readJsonObjectFile("--params-file", input.paramsFile)
+      : input.params
+        ? parseJsonObject("--params", input.params)
+        : {};
+    const residentialProxy = input.residentialProxy
+      ? parseJsonObject("--residential-proxy", input.residentialProxy)
+      : undefined;
+
+    const payload: Record<string, unknown> = {
+      workflow: input.workflow!,
+      cron_expr: input.cron!,
+      timezone: input.timezone ?? "UTC",
+      params,
+      enabled: !input.disabled,
+    };
+    if (input.timeoutSeconds !== undefined) {
+      payload.timeout_seconds = input.timeoutSeconds;
+    }
+    if (input.callbackUrl) payload.callback_url = input.callbackUrl;
+    if (input.callbackSecret) payload.callback_secret = input.callbackSecret;
+    if (input.skipCallbacks) payload.skip_callbacks = true;
+    if (residentialProxy !== undefined) {
+      payload.residential_proxy = residentialProxy;
+    }
+
+    const response = await orpcCall<CreateScheduleResponse>({
+      apiUrl: ctx.apiUrl,
+      path: "/v1/schedules/create",
+      input: payload,
+      credential: ctx.credential,
+    });
+
+    const { schedule } = response;
+    console.log(`Schedule created: ${schedule.id}`);
+    console.log(`Workflow: ${schedule.workflow}`);
+    console.log(`Cron: ${schedule.cron_expr} (${schedule.timezone})`);
+    console.log(`Next fire: ${schedule.next_fire_at}`);
+    console.log(`Enabled: ${schedule.enabled ? "yes" : "no"}`);
+    return schedule.id;
+  });
+
+export const cloudScheduleCommands = SimpleCLI.group({
+  description: "Create and manage hosted schedules",
+  routes: {
+    create: createCloudScheduleCommand,
+  },
+});

package/src/cli/commands/cloud-settings.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { SimpleCLI } from "affordance";
+import { orpcCall } from "../core/auth-fetch.js";
+import { withCloudApiKey, type CloudApiKeyContext } from "./shared.js";
+
+type TenantSettingsResponse = {
+  code_sharing_enabled: boolean;
+  disable_job_failure_notifications: boolean;
+  debug_notification_email: string | null;
+};
+
+type TenantSettingsInput = {
+  code_sharing_enabled?: boolean;
+  disable_job_failure_notifications?: boolean;
+};
+
+const settingState = z.enum(["enabled", "disabled"]);
+
+function toBoolean(state: "enabled" | "disabled"): boolean {
+  return state === "enabled";
+}
+
+function printTenantSettings(
+  settings: TenantSettingsResponse,
+): TenantSettingsResponse {
+  const notificationsEnabled = !settings.disable_job_failure_notifications;
+  console.log(
+    `Code sharing: ${settings.code_sharing_enabled ? "enabled" : "disabled"}`,
+  );
+  console.log(
+    `Job failure notifications: ${notificationsEnabled ? "enabled" : "disabled"}`,
+  );
+  console.log(
+    `Notification recipient: ${settings.debug_notification_email ?? "not configured"}`,
+  );
+  return settings;
+}
+
+async function tenantSettings(
+  ctx: CloudApiKeyContext,
+  input: TenantSettingsInput = {},
+): Promise<TenantSettingsResponse> {
+  return orpcCall<TenantSettingsResponse>({
+    apiUrl: ctx.apiUrl,
+    path: "/v1/tenant/settings",
+    input,
+    credential: ctx.credential,
+  });
+}
+
+export const settingsStatusCommand = SimpleCLI.command({
+  description: "Show Libretto Cloud tenant settings",
+})
+  .input(SimpleCLI.input({ positionals: [], named: {} }))
+  .use(withCloudApiKey("manage Libretto Cloud settings"))
+  .handle(async ({ ctx }) => printTenantSettings(await tenantSettings(ctx)));
+
+export const setSettingsCommand = SimpleCLI.command({
+  description: "Update one or more Libretto Cloud tenant settings",
+})
+  .input(
+    SimpleCLI.input({
+      positionals: [],
+      named: {
+        codeSharing: SimpleCLI.option(settingState.optional(), {
+          help: "Set tenant code sharing: enabled or disabled",
+        }),
+        jobFailureNotifications: SimpleCLI.option(settingState.optional(), {
+          help: "Set hosted job failure notification emails: enabled or disabled",
+        }),
+      },
+    }),
+  )
+  .use(withCloudApiKey("manage Libretto Cloud settings"))
+  .handle(async ({ input, ctx }) => {
+    const updates: TenantSettingsInput = {};
+    if (input.codeSharing !== undefined) {
+      updates.code_sharing_enabled = toBoolean(input.codeSharing);
+    }
+    if (input.jobFailureNotifications !== undefined) {
+      updates.disable_job_failure_notifications = !toBoolean(
+        input.jobFailureNotifications,
+      );
+    }
+
+    if (Object.keys(updates).length === 0) {
+      throw new Error(
+        "No settings provided. Use one or more flags, for example `libretto cloud settings set --code-sharing enabled --job-failure-notifications disabled`.",
+      );
+    }
+
+    return printTenantSettings(await tenantSettings(ctx, updates));
+  });
+
+export const settingsCommands = SimpleCLI.group({
+  description: "Manage Libretto Cloud tenant settings",
+  routes: {
+    status: settingsStatusCommand,
+    set: setSettingsCommand,
+  },
+});

package/src/cli/commands/cloud-sharing.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { SimpleCLI } from "affordance";
-import { orpcCall, resolveApiUrl } from "../core/auth-fetch.js";
+import { orpcCall } from "../core/auth-fetch.js";
+import { withCloudApiKey, type CloudApiKeyContext } from "./shared.js";
 
 type CodeSharingStatusResponse = {
   enabled: boolean;
@@ -14,19 +15,6 @@ type ShareWorkflowResponse = {
   code_url: string;
 };
 
-function requireCloudApiKey() {
-  const apiKey = process.env.LIBRETTO_API_KEY?.trim();
-  if (!apiKey) {
-    throw new Error(
-      "LIBRETTO_API_KEY is required to share Libretto Cloud workflow code. Issue one with `libretto cloud auth api-key issue --label <label>`.",
-    );
-  }
-  return {
-    apiUrl: resolveApiUrl(null),
-    credential: { source: "env-api-key" as const, apiKey },
-  };
-}
-
 export const shareWorkflowCommand = SimpleCLI.command({
   description: "Share one hosted workflow's code publicly",
 })
@@ -42,13 +30,13 @@ export const shareWorkflowCommand = SimpleCLI.command({
       }),
     },
   }))
-  .handle(async ({ input }) => {
-    const { apiUrl, credential } = requireCloudApiKey();
+  .use(withCloudApiKey("share Libretto Cloud workflow code"))
+  .handle(async ({ input, ctx }) => {
     const response = await orpcCall<ShareWorkflowResponse>({
-      apiUrl,
+      apiUrl: ctx.apiUrl,
       path: "/v1/workflows/share",
       input: { workflow: input.workflow, refresh: input.refresh },
-      credential,
+      credential: ctx.credential,
     });
 
     if (response.status === "existing") {
@@ -68,25 +56,27 @@ export const codeSharingStatusCommand = SimpleCLI.command({
   description: "Show whether tenant code sharing is enabled",
 })
   .input(SimpleCLI.input({ positionals: [], named: {} }))
-  .handle(async () => {
-    const { apiUrl, credential } = requireCloudApiKey();
+  .use(withCloudApiKey("manage tenant workflow code sharing"))
+  .handle(async ({ ctx }) => {
     const response = await orpcCall<CodeSharingStatusResponse>({
-      apiUrl,
+      apiUrl: ctx.apiUrl,
       path: "/v1/tenant/codeSharing",
       input: {},
-      credential,
+      credential: ctx.credential,
     });
     console.log(`Code sharing: ${response.enabled ? "enabled" : "disabled"}`);
     return response.enabled;
   });
 
-async function updateCodeSharing(enabled: boolean): Promise<boolean> {
-  const { apiUrl, credential } = requireCloudApiKey();
+async function updateCodeSharing(
+  enabled: boolean,
+  ctx: CloudApiKeyContext,
+): Promise<boolean> {
   const response = await orpcCall<CodeSharingStatusResponse>({
-    apiUrl,
+    apiUrl: ctx.apiUrl,
     path: "/v1/tenant/updateCodeSharing",
     input: { enabled },
-    credential,
+    credential: ctx.credential,
   });
   console.log(`Code sharing: ${response.enabled ? "enabled" : "disabled"}`);
   return response.enabled;
@@ -96,13 +86,15 @@ export const enableCodeSharingCommand = SimpleCLI.command({
   description: "Enable public workflow code sharing for this tenant",
 })
   .input(SimpleCLI.input({ positionals: [], named: {} }))
-  .handle(async () => updateCodeSharing(true));
+  .use(withCloudApiKey("manage tenant workflow code sharing"))
+  .handle(async ({ ctx }) => updateCodeSharing(true, ctx));
 
 export const disableCodeSharingCommand = SimpleCLI.command({
   description: "Disable public workflow code sharing for this tenant",
 })
   .input(SimpleCLI.input({ positionals: [], named: {} }))
-  .handle(async () => updateCodeSharing(false));
+  .use(withCloudApiKey("manage tenant workflow code sharing"))
+  .handle(async ({ ctx }) => updateCodeSharing(false, ctx));
 
 export const codeSharingCommands = SimpleCLI.group({
   description: "Manage tenant workflow code sharing",

package/src/cli/commands/deploy.ts

@@ -1,15 +1,13 @@
 import { randomBytes } from "node:crypto";
 import { z } from "zod";
-import {
-  orpcCall,
-  resolveApiUrl,
-} from "../core/auth-fetch.js";
+import { orpcCall } from "../core/auth-fetch.js";
 import {
   buildHostedDeployTarball,
   type WorkflowDeployMetadata,
 } from "../core/deploy-artifact.js";
 import { readAuthState } from "../core/auth-storage.js";
 import { SimpleCLI } from "affordance";
+import { withCloudApiKey } from "./shared.js";
 
 type DeploymentStatus = "building" | "ready" | "failed";
 
@@ -53,19 +51,6 @@ function deployApiKeyRequiredMessage(hasStoredSession: boolean): string {
   ].join("\n");
 }
 
-async function requireDeployApiKey() {
-  const apiKey = process.env.LIBRETTO_API_KEY?.trim();
-
-  if (!apiKey) {
-    throw new Error(deployApiKeyRequiredMessage(await hasStoredCloudSession()));
-  }
-
-  return {
-    apiUrl: resolveApiUrl(null),
-    credential: { source: "env-api-key" as const, apiKey },
-  };
-}
-
 async function hasStoredCloudSession(): Promise<boolean> {
   try {
     return Boolean((await readAuthState())?.session);
@@ -188,8 +173,12 @@ export const deployCommand = SimpleCLI.command({
   description: "Deploy workflows to the hosted platform",
 })
   .input(deployInput)
-  .handle(async ({ input }) => {
-    const { apiUrl, credential } = await requireDeployApiKey();
+  .use(withCloudApiKey(
+    "deploy to Libretto Cloud",
+    async () => deployApiKeyRequiredMessage(await hasStoredCloudSession()),
+  ))
+  .handle(async ({ input, ctx }) => {
+    const { apiUrl, credential } = ctx;
     const deploymentName = generateDeploymentName();
 
     // Hosted deploy uploads a generated artifact with a deploy entrypoint and

package/src/cli/commands/execution.ts

@@ -92,6 +92,7 @@ export function createRunBrowserConfig(args: {
     return {
       kind: "provider",
       providerName: args.providerName,
+      headless: args.headless,
     };
   }
 
@@ -895,7 +896,7 @@ export const runCommand = SimpleCLI.command({
       console.log(`Connecting to ${providerName} browser...`);
     }
 
-    const headless = daemonProviderName ? true : (headlessMode ?? false);
+    const headless = headlessMode ?? false;
     const windowPosition = headless
       ? undefined
       : resolveWindowPosition(ctx.logger);