libretto 0.4.0 → 0.4.2

package/dist/cli/commands/execution.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import * as moduleBuiltin from "node:module";
 import { fileURLToPath } from "node:url";
+import { z } from "zod";
 import { installInstrumentation } from "../../shared/instrumentation/index.js";
 import {
   connect,
@@ -12,7 +13,6 @@ import {
   assertSessionAvailableForStart,
   clearSessionState,
   readSessionState,
-  readSessionStateOrThrow,
   setSessionStatus
 } from "../core/session.js";
 import {
@@ -20,6 +20,13 @@ import {
   readNetworkLog,
   wrapPageForActionLogging
 } from "../core/telemetry.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+import {
+  loadSessionStateMiddleware,
+  pageOption,
+  resolveSessionMiddleware,
+  sessionOption
+} from "./shared.js";
 const stripTypeScriptTypes = moduleBuiltin.stripTypeScriptTypes;
 const require2 = moduleBuiltin.createRequire(import.meta.url);
 const tsxCliPath = require2.resolve("tsx/cli");
@@ -63,7 +70,6 @@ function compileExecFunction(code, helperNames) {
   return new AsyncFunction(...helperNames, code);
 }
 async function runExec(code, session, logger, visualize = false, pageId) {
-  readSessionStateOrThrow(session);
   logger.info("exec-start", {
     session,
     codeLength: code.length,
@@ -211,25 +217,24 @@ function readJsonFileIfExists(path) {
     return null;
   }
 }
-function readFailureSignal(path) {
+function readFailureDetails(path) {
   const raw = readJsonFileIfExists(path);
   if (!raw || typeof raw !== "object") return null;
   const message = raw.message;
-  if (typeof message !== "string") return null;
   const phase = raw.phase;
   return {
-    message,
+    message: typeof message === "string" ? message : void 0,
     phase: phase === "setup" || phase === "workflow" ? phase : void 0
   };
 }
-async function waitForFailureSignal(path, timeoutMs = 1e3) {
+async function waitForFailureDetails(path, timeoutMs = 1e3) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const failure = readFailureSignal(path);
-    if (failure) return failure;
+    const details = readFailureDetails(path);
+    if (details?.message) return details;
     await new Promise((resolveWait) => setTimeout(resolveWait, 25));
   }
-  return readFailureSignal(path);
+  return readFailureDetails(path);
 }
 function streamOutputSince(path, offset) {
   if (!existsSync(path)) return offset;
@@ -255,11 +260,11 @@ async function waitForWorkflowOutcome(args) {
     outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
     if (existsSync(signalPaths.failedSignalPath)) {
       outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
-      const failure = await waitForFailureSignal(signalPaths.failedSignalPath);
+      const failureDetails = await waitForFailureDetails(signalPaths.failedSignalPath);
       return {
         status: "failed",
-        message: failure?.message,
-        failurePhase: failure?.phase
+        message: failureDetails?.message,
+        phase: failureDetails?.phase
       };
     }
     if (existsSync(signalPaths.completedSignalPath)) {
@@ -277,8 +282,7 @@ async function waitForWorkflowOutcome(args) {
     await new Promise((resolveWait) => setTimeout(resolveWait, 250));
   }
 }
-async function runResume(session, logger) {
-  const state = readSessionStateOrThrow(session);
+async function runResume(session, logger, sessionState) {
   const {
     pausedSignalPath,
     resumeSignalPath,
@@ -291,9 +295,9 @@ async function runResume(session, logger) {
       `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause() first.`
     );
   }
-  if (!isProcessRunning(state.pid)) {
+  if (!isProcessRunning(sessionState.pid)) {
     throw new Error(
-      `No active paused workflow found for session "${session}" (worker pid ${state.pid} is not running).`
+      `No active paused workflow found for session "${session}" (worker pid ${sessionState.pid} is not running).`
     );
   }
   clearSignalIfExists(pausedSignalPath);
@@ -316,7 +320,7 @@ async function runResume(session, logger) {
   console.log(`Resume signal sent for session "${session}".`);
   const outcome = await waitForWorkflowOutcome({
     session,
-    pid: state.pid
+    pid: sessionState.pid
   });
   if (outcome.status === "completed") {
     setSessionStatus(session, "completed", logger);
@@ -340,7 +344,6 @@ async function runResume(session, logger) {
 }
 async function runIntegrationFromFile(args, logger) {
   await stopExistingFailedRunSession(args.session, logger);
-  assertSessionAvailableForStart(args.session, logger);
   const signalPaths = getPauseSignalPaths(args.session);
   clearSignalIfExists(signalPaths.pausedSignalPath);
   clearSignalIfExists(signalPaths.resumeSignalPath);
@@ -380,14 +383,13 @@ async function runIntegrationFromFile(args, logger) {
   }
   if (outcome.status === "failed") {
     setSessionStatus(args.session, "failed", logger);
-    const message = outcome.message ?? "Workflow failed during run.";
-    if (outcome.failurePhase === "workflow") {
+    if (outcome.phase === "workflow") {
       throw new Error(
-        `${message}
+        `${outcome.message ?? "Workflow failed during run."}
 Browser is still open. You can use \`exec\` to inspect it. Call \`run\` to re-run the workflow.`
       );
     }
-    throw new Error(message);
+    throw new Error(outcome.message ?? "Workflow failed during run.");
   }
   if (outcome.status === "exited") {
     setSessionStatus(args.session, "exited", logger);
@@ -396,95 +398,132 @@ Browser is still open. You can use \`exec\` to inspect it. Call \`run\` to re-ru
     );
   }
   setSessionStatus(args.session, "completed", logger);
+  console.log("Integration completed.");
+}
+const execInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("codeParts", z.array(z.string()).default([]), {
+      help: "Playwright TypeScript code to execute",
+      variadic: true
+    })
+  ],
+  named: {
+    session: sessionOption(),
+    visualize: SimpleCLI.flag({ help: "Enable ghost cursor + highlight visualization" }),
+    page: pageOption()
+  }
+}).refine(
+  (input) => input.codeParts.length > 0,
+  "Usage: libretto-cli exec <code> [--session <name>] [--visualize]"
+);
+function createExecCommand(logger) {
+  return SimpleCLI.command({
+    description: "Execute Playwright TypeScript code"
+  }).input(execInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ input, ctx }) => {
+    await runExec(
+      input.codeParts.join(" "),
+      ctx.session,
+      logger,
+      input.visualize,
+      input.page
+    );
+  });
 }
-function registerExecutionCommands(yargs, logger) {
-  return yargs.command(
-    "exec [code..]",
-    "Execute Playwright TypeScript code",
-    (cmd) => cmd.option("visualize", { type: "boolean", default: false }).option("page", { type: "string" }),
-    async (argv) => {
-      const codeParts = Array.isArray(argv.code) ? argv.code : argv.code ? [String(argv.code)] : [];
-      const code = codeParts.join(" ");
-      if (!code) {
-        throw new Error(
-          "Usage: libretto-cli exec <code> [--session <name>] [--visualize]"
-        );
-      }
-      await runExec(
-        code,
-        String(argv.session),
-        logger,
-        Boolean(argv.visualize),
-        argv.page ? String(argv.page) : void 0
+const runUsage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]";
+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"
+    })
+  ],
+  named: {
+    session: sessionOption(),
+    params: SimpleCLI.option(z.string().optional(), {
+      help: "Inline JSON params"
+    }),
+    paramsFile: SimpleCLI.option(z.string().optional(), {
+      name: "params-file",
+      help: "Path to a JSON params file"
+    }),
+    tsconfig: SimpleCLI.option(z.string().optional(), {
+      help: "Path to a tsconfig used for workflow module resolution"
+    }),
+    headed: SimpleCLI.flag({ help: "Run in headed mode" }),
+    headless: SimpleCLI.flag({ help: "Run in headless mode" }),
+    authProfile: SimpleCLI.option(z.string().optional(), {
+      name: "auth-profile",
+      help: "Domain for local auth profile (e.g. apps.example.com)"
+    })
+  }
+}).refine(
+  (input) => Boolean(input.integrationFile && input.integrationExport),
+  runUsage
+).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.");
+function resolveRunParams(rawInlineParams, paramsFile) {
+  if (paramsFile) {
+    let content;
+    try {
+      content = readFileSync(paramsFile, "utf8");
+    } catch {
+      throw new Error(
+        `Could not read --params-file "${paramsFile}". Ensure the file exists and is readable.`
       );
     }
-  ).command(
-    "run [integrationFile] [integrationExport]",
-    "Run an exported Libretto workflow from a file",
-    (cmd) => cmd.option("params", { type: "string" }).option("params-file", { type: "string" }).option("tsconfig", { type: "string" }).option("headed", { type: "boolean", default: false }).option("headless", { type: "boolean", default: false }).option("auth-profile", { type: "string", describe: "Domain for local auth profile (e.g. apps.example.com)" }),
-    async (argv) => {
-      const usage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]";
-      const integrationPath = argv.integrationFile;
-      const exportName = argv.integrationExport;
-      const legacyDebug = argv.debug;
-      if (legacyDebug !== void 0) {
-        throw new Error(
-          "The --debug flag has been removed. Run the command without --debug."
-        );
-      }
-      if (!integrationPath || !exportName) {
-        throw new Error(usage);
-      }
-      const session = String(argv.session);
-      const rawInlineParams = argv.params;
-      const paramsFile = argv["params-file"];
-      if (rawInlineParams && paramsFile) {
-        throw new Error("Pass either --params or --params-file, not both.");
-      }
-      const params = (() => {
-        if (paramsFile) {
-          let content;
-          try {
-            content = readFileSync(paramsFile, "utf8");
-          } catch {
-            throw new Error(
-              `Could not read --params-file "${paramsFile}". Ensure the file exists and is readable.`
-            );
-          }
-          return parseJsonArg("--params-file", content);
-        }
-        if (rawInlineParams) {
-          return parseJsonArg("--params", rawInlineParams);
-        }
-        return {};
-      })();
-      const hasHeadedFlag = Boolean(argv.headed);
-      const hasHeadlessFlag = Boolean(argv.headless);
-      if (hasHeadedFlag && hasHeadlessFlag) {
-        throw new Error("Cannot pass both --headed and --headless.");
-      }
-      const headlessMode = hasHeadedFlag ? false : hasHeadlessFlag ? true : void 0;
-      const authProfileDomain = argv["auth-profile"];
-      const tsconfigPath = argv.tsconfig;
-      await runIntegrationFromFile({
-        integrationPath,
-        exportName,
-        session,
-        params,
-        headless: headlessMode ?? false,
-        authProfileDomain,
-        tsconfigPath
-      }, logger);
-    }
-  ).command(
-    "resume",
-    "Resume a paused workflow for the current session",
-    (cmd) => cmd,
-    async (argv) => {
-      await runResume(String(argv.session), logger);
-    }
-  );
+    return parseJsonArg("--params-file", content);
+  }
+  if (rawInlineParams) {
+    return parseJsonArg("--params", rawInlineParams);
+  }
+  return {};
+}
+function createRunCommand(logger) {
+  return SimpleCLI.command({
+    description: "Run an exported Libretto workflow from a file"
+  }).input(runInput).use(resolveSessionMiddleware).handle(async ({ input, ctx }) => {
+    await stopExistingFailedRunSession(ctx.session, logger);
+    assertSessionAvailableForStart(ctx.session, logger);
+    const params = resolveRunParams(input.params, input.paramsFile);
+    const headlessMode = input.headed ? false : input.headless ? true : void 0;
+    await runIntegrationFromFile({
+      integrationPath: input.integrationFile,
+      exportName: input.integrationExport,
+      session: ctx.session,
+      params,
+      tsconfigPath: input.tsconfig,
+      headless: headlessMode ?? false,
+      authProfileDomain: input.authProfile
+    }, logger);
+  });
+}
+const resumeInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    session: sessionOption()
+  }
+});
+function createResumeCommand(logger) {
+  return SimpleCLI.command({
+    description: "Resume a paused workflow for the current session"
+  }).input(resumeInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ ctx }) => {
+    await runResume(ctx.session, logger, ctx.sessionState);
+  });
+}
+function createExecutionCommands(logger) {
+  return {
+    exec: createExecCommand(logger),
+    run: createRunCommand(logger),
+    resume: createResumeCommand(logger)
+  };
 }
 export {
-  registerExecutionCommands
+  createExecCommand,
+  createExecutionCommands,
+  createResumeCommand,
+  createRunCommand,
+  execInput,
+  resumeInput,
+  runInput
 };

package/dist/cli/commands/init.js

@@ -1,15 +1,15 @@
 import { createInterface } from "node:readline";
-import { existsSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-import {
-  readAiConfig
-} from "../core/ai-config.js";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readAiConfig } from "../core/ai-config.js";
 import { REPO_ROOT } from "../core/context.js";
 import {
   loadSnapshotEnv,
   resolveSnapshotApiModel
 } from "../core/snapshot-api-config.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
 import { hasProviderCredentials } from "../../shared/llm/client.js";
 const PROVIDER_CHOICES = [
   {
@@ -44,6 +44,15 @@ function promptUser(rl, question) {
     });
   });
 }
+function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
 function safeReadAiConfig() {
   try {
     return readAiConfig();
@@ -61,9 +70,7 @@ function printSnapshotApiStatus() {
   );
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
   if (selection && hasProviderCredentials(selection.provider)) {
-    console.log(
-      `  \u2713 Ready: ${selection.model} (${selection.source})`
-    );
+    console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
     console.log("    No further action required.");
     return;
@@ -86,14 +93,10 @@ async function runInteractiveApiSetup() {
   const selection = resolveSnapshotApiModel(config);
   const envPath = join(REPO_ROOT, ".env");
   console.log("\nSnapshot analysis setup:");
-  console.log(
-    "  Libretto uses direct API calls for snapshot analysis."
-  );
+  console.log("  Libretto uses direct API calls for snapshot analysis.");
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
   if (selection && hasProviderCredentials(selection.provider)) {
-    console.log(
-      `  \u2713 Ready: ${selection.model} (${selection.source})`
-    );
+    console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
     return;
   }
@@ -120,7 +123,7 @@ async function runInteractiveApiSetup() {
       );
       return;
     }
-    const selected = PROVIDER_CHOICES.find((c) => c.key === answer);
+    const selected = PROVIDER_CHOICES.find((choice) => choice.key === answer);
     if (!selected) {
       console.log(`
   Unknown choice "${answer}". Skipping API setup.`);
@@ -130,7 +133,10 @@ async function runInteractiveApiSetup() {
   ${selected.label} selected.`);
     console.log(`  ${selected.envHint}
 `);
-    const apiKeyValue = await promptUser(rl, `  Enter your ${selected.envVar}: `);
+    const apiKeyValue = await promptUser(
+      rl,
+      `  Enter your ${selected.envVar}: `
+    );
     if (!apiKeyValue) {
       console.log("\n  No value entered. Skipping API key setup.");
       return;
@@ -179,31 +185,88 @@ function installBrowsers() {
     );
   }
 }
-function registerInitCommand(yargs) {
-  return yargs.command(
-    "init",
-    "Initialize libretto in the current project",
-    (cmd) => cmd.option("skip-browsers", {
-      type: "boolean",
-      default: false,
-      describe: "Skip Playwright Chromium installation"
-    }),
-    async (argv) => {
-      console.log("Initializing libretto...\n");
-      if (!argv["skip-browsers"]) {
-        installBrowsers();
-      } else {
-        console.log("\nSkipping browser installation (--skip-browsers)");
-      }
-      if (process.stdin.isTTY) {
-        await runInteractiveApiSetup();
-      } else {
-        printSnapshotApiStatus();
-      }
-      console.log("\n\u2713 libretto init complete");
+function getPackageSkillsDir() {
+  const thisFile = fileURLToPath(import.meta.url);
+  let dir = dirname(thisFile);
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "skills", "libretto"))) {
+      return join(dir, "skills", "libretto");
     }
-  );
+    dir = dirname(dir);
+  }
+  throw new Error("Could not locate libretto skill files in package");
 }
+async function copySkills() {
+  const cwd = process.cwd();
+  const agentDirs = [];
+  if (existsSync(join(cwd, ".agents"))) {
+    agentDirs.push({
+      name: ".agents",
+      skillDest: join(cwd, ".agents", "skills", "libretto")
+    });
+  }
+  if (existsSync(join(cwd, ".claude"))) {
+    agentDirs.push({
+      name: ".claude",
+      skillDest: join(cwd, ".claude", "skills", "libretto")
+    });
+  }
+  if (agentDirs.length === 0) {
+    console.log("\nSkills: No .agents/ or .claude/ directory found \u2014 skipping skill copy.");
+    return;
+  }
+  const dirNames = agentDirs.map((d) => d.name).join(" and ");
+  const existing = agentDirs.filter((d) => existsSync(d.skillDest));
+  const verb = existing.length > 0 ? "Overwrite" : "Install";
+  const proceed = await askYesNo(`
+${verb} libretto skills in ${dirNames}?`);
+  if (!proceed) {
+    console.log("  Skipping skill copy.");
+    return;
+  }
+  let sourceDir;
+  try {
+    sourceDir = getPackageSkillsDir();
+  } catch (e) {
+    console.error(`  \u2717 ${e instanceof Error ? e.message : String(e)}`);
+    return;
+  }
+  for (const { name, skillDest } of agentDirs) {
+    if (existsSync(skillDest)) {
+      rmSync(skillDest, { recursive: true });
+    }
+    cpSync(sourceDir, skillDest, { recursive: true });
+    const fileCount = readdirSync(skillDest).length;
+    console.log(`  \u2713 Copied ${fileCount} skill files to ${name}/skills/libretto/`);
+  }
+}
+const initInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    skipBrowsers: SimpleCLI.flag({
+      name: "skip-browsers",
+      help: "Skip Playwright Chromium installation"
+    })
+  }
+});
+const initCommand = SimpleCLI.command({
+  description: "Initialize libretto in the current project"
+}).input(initInput).handle(async ({ input }) => {
+  console.log("Initializing libretto...\n");
+  if (!input.skipBrowsers) {
+    installBrowsers();
+  } else {
+    console.log("\nSkipping browser installation (--skip-browsers)");
+  }
+  if (process.stdin.isTTY) {
+    await copySkills();
+    await runInteractiveApiSetup();
+  } else {
+    printSnapshotApiStatus();
+  }
+  console.log("\n\u2713 libretto init complete");
+});
 export {
-  registerInitCommand
+  initCommand,
+  initInput
 };