@openfn/cli 1.2.5 → 1.3.1

package/dist/index.js

@@ -171,6 +171,29 @@ var autoinstall = {
     default: true
   }
 };
+var apolloUrl = {
+  name: "apollo-url",
+  yargs: {
+    alias: ["url"],
+    description: "Auto-install the language adaptor(s)"
+  },
+  // map local, staging, prod to apollo-url
+  ensure: (opts2) => {
+    let didLoadShortcut = false;
+    ["local", "staging", "prod", "production"].forEach((shortcut) => {
+      if (shortcut in opts2) {
+        if (didLoadShortcut) {
+          throw new Error(
+            "Invalid apollo URL - please only enter one of local, staging or prod"
+          );
+        }
+        opts2.apolloUrl = shortcut;
+        delete opts2[shortcut];
+        didLoadShortcut = true;
+      }
+    });
+  }
+};
 var cacheSteps = {
   name: "cache-steps",
   yargs: {
@@ -319,7 +342,7 @@ var outputPath = {
     description: "Path to the output file"
   },
   ensure: (opts2) => {
-    if (opts2.command == "compile") {
+    if (/^(compile|apollo)$/.test(opts2.command)) {
       if (opts2.outputPath) {
         delete opts2.outputStdout;
       }
@@ -476,8 +499,36 @@ var override = (command, yargs2) => {
   };
 };
 
-// src/compile/command.ts
+// src/apollo/util.ts
+var STAGING_URL = "http://34.95.82.109";
+
+// src/apollo/command.ts
 var options = [
+  apolloUrl,
+  stateStdin,
+  log,
+  logJson,
+  outputPath,
+  override(outputStdout, {
+    default: true
+  })
+];
+var desc = `Call services on the openfn apollo server. Set the local server location with OPENFN_APOLLO_SERVER. The staging server is set to ${STAGING_URL}`;
+var command_default = {
+  command: "apollo <service> [payload]",
+  desc,
+  handler: ensure("apollo", options),
+  builder: (yargs2) => build(options, yargs2).example(
+    "apollo echo path/to/json",
+    "Call the echo service, which returns json back"
+  ).example(
+    "apollo adaptor_gen cat-facts.example.json --local",
+    "Generate an adaptor template against a local server"
+  )
+};
+
+// src/compile/command.ts
+var options2 = [
   expandAdaptors,
   adaptors,
   ignoreImports,
@@ -494,8 +545,8 @@ var options = [
 var compileCommand = {
   command: "compile [path]",
   describe: "Compile an openfn job or workflow and print or save the resulting JavaScript.",
-  handler: ensure("compile", options),
-  builder: (yargs2) => build(options, yargs2).positional("path", {
+  handler: ensure("compile", options2),
+  builder: (yargs2) => build(options2, yargs2).positional("path", {
     describe: "The path to load the job or workflow from (a .js or .json file or a dir containing a job.js file)",
     demandOption: true
   }).example(
@@ -506,10 +557,10 @@ var compileCommand = {
     "Compiles the workflow at foo/work.json and prints the result to -o foo/workflow-compiled.json"
   )
 };
-var command_default = compileCommand;
+var command_default2 = compileCommand;
 
 // src/deploy/command.ts
-var options2 = [
+var options3 = [
   configPath,
   confirm,
   describe,
@@ -521,10 +572,10 @@ var options2 = [
 var deployCommand = {
   command: "deploy",
   describe: "Deploy a project's config to a remote Lightning instance",
-  handler: ensure("deploy", options2),
-  builder: (yargs2) => build(options2, yargs2)
+  handler: ensure("deploy", options3),
+  builder: (yargs2) => build(options3, yargs2)
 };
-var command_default2 = deployCommand;
+var command_default3 = deployCommand;
 
 // src/docgen/command.ts
 var docgenCommand = {
@@ -537,23 +588,23 @@ var docgenCommand = {
   },
   builder: (yargs2) => yargs2.example("docgen @openfn/language-common@1.7.5", "")
 };
-var command_default3 = docgenCommand;
+var command_default4 = docgenCommand;
 
 // src/docs/command.ts
-var options3 = [log, logJson, repoDir];
+var options4 = [log, logJson, repoDir];
 var docsCommand = {
   command: "docs <adaptor> [operation]",
   describe: "Print help for an adaptor function. You can use short-hand for adaptor names (ie, common instead of @openfn/language-common)",
-  handler: ensure("docs", options3),
-  builder: (yargs2) => build(options3, yargs2).example(
+  handler: ensure("docs", options4),
+  builder: (yargs2) => build(options4, yargs2).example(
     "docs common fn",
     "Print help for the common fn operation"
   )
 };
-var command_default4 = docsCommand;
+var command_default5 = docsCommand;
 
 // src/execute/command.ts
-var options4 = [
+var options5 = [
   expandAdaptors,
   adaptors,
   autoinstall,
@@ -585,8 +636,8 @@ Execute will run a expression/workflow at the path and write the output state to
   
 Remember to include the adaptor name with -a. Auto install adaptors with the -i flag.`,
   aliases: ["$0"],
-  handler: ensure("execute", options4),
-  builder: (yargs2) => build(options4, yargs2).positional("path", {
+  handler: ensure("execute", options5),
+  builder: (yargs2) => build(options5, yargs2).positional("path", {
     describe: "The path to load the job or workflow from (a .js or .json file or a dir containing a job.js file)",
     demandOption: true
   }).example(
@@ -603,10 +654,10 @@ Remember to include the adaptor name with -a. Auto install adaptors with the -i
     "Compile the expression at job.js with the http adaptor and print the code to stdout"
   )
 };
-var command_default5 = executeCommand;
+var command_default6 = executeCommand;
 
 // src/metadata/command.ts
-var options5 = [
+var options6 = [
   expandAdaptors,
   adaptors,
   force,
@@ -617,31 +668,31 @@ var options5 = [
   stateStdin,
   useAdaptorsMonorepo
 ];
-var command_default6 = {
+var command_default7 = {
   command: "metadata",
   describe: "Generate metadata for an adaptor config",
-  handler: ensure("metadata", options5),
-  builder: (yargs2) => build(options5, yargs2).example(
+  handler: ensure("metadata", options6),
+  builder: (yargs2) => build(options6, yargs2).example(
     "metadata -a salesforce -s tmp/state.json",
     "Generate salesforce metadata from config in state.json"
   )
 };
 
 // src/pull/command.ts
-var options6 = [statePath, projectPath, configPath, log, logJson];
+var options7 = [statePath, projectPath, configPath, log, logJson];
 var pullCommand = {
   command: "pull [projectId]",
   describe: "Pull a project's state and spec from a Lightning Instance to the local directory",
-  builder: (yargs2) => build(options6, yargs2).positional("projectId", {
+  builder: (yargs2) => build(options7, yargs2).positional("projectId", {
     describe: "The id of the project that should be pulled shouled be a UUID",
     demandOption: true
   }).example(
     "pull 57862287-23e6-4650-8d79-e1dd88b24b1c",
     "Pull an updated copy of a the above spec and state from a Lightning Instance"
   ),
-  handler: ensure("pull", options6)
+  handler: ensure("pull", options7)
 };
-var command_default7 = pullCommand;
+var command_default8 = pullCommand;
 
 // src/repo/command.ts
 var repo = {
@@ -702,17 +753,17 @@ var list = {
 };
 
 // src/test/command.ts
-var options7 = [stateStdin, log, logJson];
-var command_default8 = {
+var options8 = [stateStdin, log, logJson];
+var command_default9 = {
   command: "test",
   desc: "Compiles and runs a test job, printing the result to stdout",
-  handler: ensure("test", options7),
-  builder: (yargs2) => build(options7, yargs2).example("test", "Run the test script")
+  handler: ensure("test", options8),
+  builder: (yargs2) => build(options8, yargs2).example("test", "Run the test script")
 };
 
 // src/cli.ts
 var y = yargs(hideBin(process.argv));
-var cmd = y.command(command_default5).command(command_default).command(command_default2).command(install).command(repo).command(command_default8).command(command_default4).command(command_default6).command(command_default3).command(command_default7).command({
+var cmd = y.command(command_default6).command(command_default2).command(command_default3).command(install).command(repo).command(command_default9).command(command_default5).command(command_default).command(command_default7).command(command_default4).command(command_default8).command({
   command: "version",
   describe: "Show the currently installed version of the CLI, compiler and runtime.",
   handler: (argv) => {

package/dist/process/runner.js

@@ -1,3 +1,144 @@
+// src/apollo/handler.ts
+import { WebSocket } from "ws";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import createLogger from "@openfn/logger";
+
+// src/apollo/util.ts
+var PRODUCTION_URL = "https://apollo.openfn.org";
+var STAGING_URL = "http://34.95.82.109";
+var LOCAL_URL = "http://localhost:3000";
+var urlMap = {
+  ["prod"]: PRODUCTION_URL,
+  ["production"]: PRODUCTION_URL,
+  ["staging"]: STAGING_URL,
+  ["local"]: LOCAL_URL
+};
+var DEFAULT_ENV = "staging";
+var getURL = (options) => {
+  if (options.apolloUrl) {
+    if (options.apolloUrl in urlMap) {
+      return urlMap[options.apolloUrl];
+    }
+    if (options.apolloUrl.startsWith("http")) {
+      return options.apolloUrl;
+    }
+    throw new Error(`Unrecognised apollo URL`);
+  }
+  const userDefault = process.env.OPENFN_APOLLO_DEFAULT_ENV || DEFAULT_ENV;
+  if (!/^(staging|prod|production|local|http*)$/.test(userDefault)) {
+    throw new Error(`Unrecognised apollo URL loaded from env: ${userDefault}`);
+  }
+  return urlMap[userDefault || "staging"];
+};
+var outputFiles = (files, logger) => {
+  logger.print();
+  for (const k in files) {
+    const line = new Array(k.length + 1).fill("-").join("");
+    logger.print(line);
+    logger.print(`${k}`);
+    logger.print(line);
+    logger.print();
+    logger.print(files[k]);
+    logger.print();
+    logger.print();
+  }
+};
+
+// src/apollo/handler.ts
+var apolloHandler = async (options, logger) => {
+  logger.always(`Calling Apollo service: ${options.service}`);
+  const json = await loadPayload(logger, options.payload);
+  const url2 = getURL(options);
+  logger.success(`Using apollo server at`, url2);
+  const result = await callApollo(url2, options.service, json, logger);
+  if (result) {
+    await serializeOutput(options, result, logger);
+  } else {
+    logger.warn("No output returned from Apollo");
+  }
+  logger.success("Done!");
+};
+var write = async (basePath, filePath, content, logger) => {
+  const ext = path.extname(basePath);
+  let dir;
+  if (ext) {
+    dir = path.dirname(path.resolve(basePath));
+  } else {
+    dir = basePath;
+  }
+  await mkdir(dir, { recursive: true });
+  console.log(content);
+  const dest = path.resolve(basePath, filePath);
+  await writeFile(dest, content);
+  logger.success(`Wrote content to ${dest}`);
+};
+var serializeOutput = async (options, result, logger) => {
+  if (options.outputPath) {
+    if (result.files && !options.outputPath.endsWith(".json")) {
+      for (const p in result.files) {
+        await write(options.outputPath, p, result.files[p], logger);
+      }
+    } else {
+      await write(
+        options.outputPath,
+        "",
+        JSON.stringify(result, null, 2),
+        logger
+      );
+    }
+    return;
+  }
+  logger.success("Result:");
+  if (result.files) {
+    outputFiles(result.files, logger);
+  } else {
+    logger.always(JSON.stringify(result, void 0, 2));
+  }
+};
+var callApollo = async (apolloBaseUrl, serviceName, payload, logger) => {
+  return new Promise((resolve) => {
+    const apolloLogger = createLogger("APO", { level: "debug" });
+    const url2 = `${apolloBaseUrl.replace(
+      /^http/,
+      "ws"
+    )}/services/${serviceName}`;
+    logger.always("Calling apollo: ", url2);
+    const socket = new WebSocket(url2);
+    socket.addEventListener("message", ({ data }) => {
+      const evt = JSON.parse(data);
+      if (evt.event === "complete") {
+        logger.debug("Apollo responded with: ", evt.data);
+        resolve(evt.data);
+      } else if (evt.event === "log") {
+        apolloLogger.info(evt.data);
+      }
+    });
+    socket.addEventListener("open", () => {
+      socket.send(
+        JSON.stringify({
+          event: "start",
+          data: payload
+        })
+      );
+    });
+  });
+};
+var loadPayload = async (logger, path9) => {
+  if (!path9) {
+    logger.warn("No JSON payload provided");
+    logger.warn("Most apollo services require JSON to be uploaded");
+    return {};
+  }
+  if (path9.endsWith(".json")) {
+    const str = await readFile(path9, "utf8");
+    const json = JSON.parse(str);
+    logger.debug("Loaded JSON payload");
+    return json;
+  }
+};
+var handler_default = apolloHandler;
+
 // src/execute/execute.ts
 import run, { NOTIFY_JOB_COMPLETE, getNameAndVersion } from "@openfn/runtime";
 
@@ -14,7 +155,7 @@ var namespaces = {
   [COMPILER]: "CMP",
   [JOB]: "JOB"
 };
-var createLogger = (name = "", options) => {
+var createLogger2 = (name = "", options) => {
   const logOptions = options.log || {};
   let json = false;
   let level = logOptions[name] || logOptions.default || "default";
@@ -28,25 +169,25 @@ var createLogger = (name = "", options) => {
     ...logOptions
   });
 };
-var logger_default = createLogger;
-var createNullLogger = () => createLogger(void 0, { log: { default: "none" } });
+var logger_default = createLogger2;
+var createNullLogger = () => createLogger2(void 0, { log: { default: "none" } });
 
 // src/util/cache.ts
 import fs from "node:fs";
-import path from "node:path";
+import path2 from "node:path";
 import { rmdir } from "node:fs/promises";
 var getCachePath = async (plan, options, stepId) => {
   const { baseDir } = options;
   const { name } = plan.workflow;
   const basePath = `${baseDir}/.cli-cache/${name}`;
   if (stepId) {
-    return path.resolve(`${basePath}/${stepId.replace(/ /, "-")}.json`);
+    return path2.resolve(`${basePath}/${stepId.replace(/ /, "-")}.json`);
   }
-  return path.resolve(basePath);
+  return path2.resolve(basePath);
 };
 var ensureGitIgnore = (options) => {
   if (!options._hasGitIgnore) {
-    const ignorePath = path.resolve(
+    const ignorePath = path2.resolve(
       options.baseDir,
       ".cli-cache",
       ".gitignore"
@@ -62,7 +203,7 @@ var ensureGitIgnore = (options) => {
 var saveToCache = async (plan, stepId, output, options, logger) => {
   if (options.cacheSteps) {
     const cachePath = await getCachePath(plan, options, stepId);
-    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.mkdirSync(path2.dirname(cachePath), { recursive: true });
     ensureGitIgnore(options);
     logger.info(`Writing ${stepId} output to ${cachePath}`);
     fs.writeFileSync(cachePath, JSON.stringify(output));
@@ -112,13 +253,13 @@ var execute_default = async (plan, input, opts, logger) => {
 };
 function parseAdaptors(plan) {
   const extractInfo = (specifier) => {
-    const [module, path8] = specifier.split("=");
+    const [module, path9] = specifier.split("=");
     const { name, version } = getNameAndVersion(module);
     const info = {
       name
     };
-    if (path8) {
-      info.path = path8;
+    if (path9) {
+      info.path = path9;
     }
     if (version) {
       info.version = version;
@@ -137,8 +278,8 @@ function parseAdaptors(plan) {
 }
 
 // src/execute/serialize-output.ts
-import { writeFile } from "node:fs/promises";
-var serializeOutput = async (options, result, logger) => {
+import { writeFile as writeFile2 } from "node:fs/promises";
+var serializeOutput2 = async (options, result, logger) => {
   let output = result;
   if (output && (output.configuration || output.data)) {
     const { configuration, ...rest } = result;
@@ -154,12 +295,12 @@ var serializeOutput = async (options, result, logger) => {
     logger.always(output);
   } else if (options.outputPath) {
     logger.debug(`Writing output to ${options.outputPath}`);
-    await writeFile(options.outputPath, output);
+    await writeFile2(options.outputPath, output);
     logger.success(`State written to ${options.outputPath}`);
   }
   return output;
 };
-var serialize_output_default = serializeOutput;
+var serialize_output_default = serializeOutput2;
 
 // src/execute/get-autoinstall-targets.ts
 var getAutoinstallTargets = (plan) => {
@@ -324,10 +465,10 @@ var stripVersionSpecifier = (specifier) => {
   return specifier;
 };
 var resolveSpecifierPath = async (pattern, repoDir, log) => {
-  const [specifier, path8] = pattern.split("=");
-  if (path8) {
-    log.debug(`Resolved ${specifier} to path: ${path8}`);
-    return path8;
+  const [specifier, path9] = pattern.split("=");
+  if (path9) {
+    log.debug(`Resolved ${specifier} to path: ${path9}`);
+    return path9;
   }
   const repoPath = await getModulePath(specifier, repoDir, log);
   if (repoPath) {
@@ -344,16 +485,16 @@ var loadTransformOptions = async (opts, log) => {
     const [pattern] = opts.adaptors;
     const [specifier] = pattern.split("=");
     log.debug(`Trying to preload types for ${specifier}`);
-    const path8 = await resolveSpecifierPath(pattern, opts.repoDir, log);
-    if (path8) {
+    const path9 = await resolveSpecifierPath(pattern, opts.repoDir, log);
+    if (path9) {
       try {
         exports = await preloadAdaptorExports(
-          path8,
+          path9,
           opts.useAdaptorsMonorepo,
           log
         );
       } catch (e) {
-        log.error(`Failed to load adaptor typedefs from path ${path8}`);
+        log.error(`Failed to load adaptor typedefs from path ${path9}`);
         log.error(e);
       }
     }
@@ -489,7 +630,7 @@ var validate_adaptors_default = validateAdaptors;
 
 // src/util/load-plan.ts
 import fs3 from "node:fs/promises";
-import path3 from "node:path";
+import path4 from "node:path";
 import { isPath } from "@openfn/compiler";
 
 // src/util/expand-adaptors.ts
@@ -518,13 +659,13 @@ var expand_adaptors_default = (input) => {
 };
 
 // src/util/map-adaptors-to-monorepo.ts
-import { readFile } from "node:fs/promises";
-import path2 from "node:path";
+import { readFile as readFile2 } from "node:fs/promises";
+import path3 from "node:path";
 import assert from "node:assert";
 import { getNameAndVersion as getNameAndVersion2 } from "@openfn/runtime";
 var validateMonoRepo = async (repoPath, log) => {
   try {
-    const raw = await readFile(`${repoPath}/package.json`, "utf8");
+    const raw = await readFile2(`${repoPath}/package.json`, "utf8");
     const pkg = JSON.parse(raw);
     assert(pkg.name === "adaptors");
   } catch (e) {
@@ -543,7 +684,7 @@ var updatePath = (adaptor, repoPath, log) => {
     );
   }
   const shortName = name.replace("@openfn/language-", "");
-  const abspath = path2.resolve(repoPath, "packages", shortName);
+  const abspath = path3.resolve(repoPath, "packages", shortName);
   log.info(`Mapped adaptor ${name} to monorepo: ${abspath}`);
   return `${name}=${abspath}`;
 };
@@ -574,10 +715,10 @@ var loadPlan = async (options, logger) => {
   }
   const jsonPath = planPath || workflowPath;
   if (!options.baseDir) {
-    options.baseDir = path3.dirname(jsonPath);
+    options.baseDir = path4.dirname(jsonPath);
   }
   const json = await loadJson(jsonPath, logger);
-  const defaultName = path3.parse(jsonPath).name;
+  const defaultName = path4.parse(jsonPath).name;
   if (json.workflow) {
     return loadXPlan(json, options, logger, defaultName);
   } else {
@@ -623,7 +764,7 @@ var loadExpression = async (options, logger) => {
   logger.debug(`Loading expression from ${expressionPath}`);
   try {
     const expression = await fs3.readFile(expressionPath, "utf8");
-    const name = path3.parse(expressionPath).name;
+    const name = path4.parse(expressionPath).name;
     const step = { expression };
     if (options.adaptors) {
       const [adaptor] = options.adaptors;
@@ -670,7 +811,7 @@ var loadOldWorkflow = async (workflow, options, logger, defaultName = "") => {
 };
 var fetchFile = async (jobId, rootDir = "", filePath, log) => {
   try {
-    const fullPath = filePath.startsWith("~") ? filePath : path3.resolve(rootDir, filePath);
+    const fullPath = filePath.startsWith("~") ? filePath : path4.resolve(rootDir, filePath);
     const result = await fs3.readFile(fullPath, "utf8");
     log.debug("Loaded file", fullPath);
     return result;
@@ -733,8 +874,8 @@ var loadXPlan = async (plan, options, logger, defaultName = "") => {
 };
 
 // src/util/assert-path.ts
-var assert_path_default = (path8) => {
-  if (!path8) {
+var assert_path_default = (path9) => {
+  if (!path9) {
     console.error("ERROR: no path provided!");
     console.error("\nUsage:");
     console.error("  open path/to/job");
@@ -768,6 +909,56 @@ var fuzzy_match_step_default = (plan, stepPattern) => {
   }
 };
 
+// src/util/validate-plan.ts
+var assertWorkflowStructure = (plan, logger) => {
+  const { workflow, options } = plan;
+  if (!workflow || typeof workflow !== "object") {
+    throw new Error(`Missing or invalid "workflow" key in execution plan`);
+  }
+  if (!Array.isArray(workflow.steps)) {
+    throw new Error("The workflow.steps key must be an array");
+  }
+  if (workflow.steps.length === 0) {
+    logger.warn("The workflow.steps array is empty");
+  }
+  workflow.steps.forEach((step, index) => {
+    assertStepStructure(step, index);
+  });
+  assertOptionsStructure(options, logger);
+};
+var assertStepStructure = (step, index) => {
+  const allowedKeys = [
+    "id",
+    "name",
+    "next",
+    "previous",
+    "adaptor",
+    "expression",
+    "state",
+    "configuration",
+    "linker"
+  ];
+  for (const key in step) {
+    if (!allowedKeys.includes(key)) {
+      throw new Error(`Invalid key "${key}" in step ${step.id || index}`);
+    }
+  }
+  if ("adaptor" in step && !("expression" in step)) {
+    throw new Error(
+      `Step ${step.id ?? index} with an adaptor must also have an expression`
+    );
+  }
+};
+var assertOptionsStructure = (options = {}, logger) => {
+  const allowedKeys = ["timeout", "stepTimeout", "start", "end", "sanitize"];
+  for (const key in options) {
+    if (!allowedKeys.includes(key)) {
+      logger.warn(`Unrecognized option "${key}" in options object`);
+    }
+  }
+};
+var validate_plan_default = assertWorkflowStructure;
+
 // src/execute/handler.ts
 var matchStep = (plan, stepPattern, stepName, logger) => {
   try {
@@ -793,6 +984,7 @@ var executeHandler = async (options, logger) => {
   assert_path_default(options.path);
   await validate_adaptors_default(options, logger);
   let plan = await load_plan_default(options, logger);
+  validate_plan_default(plan, logger);
   if (options.cacheSteps) {
     await clearCache(plan, options, logger);
   }
@@ -876,10 +1068,10 @@ var executeHandler = async (options, logger) => {
     process.exitCode = 1;
   }
 };
-var handler_default = executeHandler;
+var handler_default2 = executeHandler;
 
 // src/compile/handler.ts
-import { writeFile as writeFile2 } from "node:fs/promises";
+import { writeFile as writeFile3 } from "node:fs/promises";
 var compileHandler = async (options, logger) => {
   assert_path_default(options.path);
   let result;
@@ -893,11 +1085,11 @@ var compileHandler = async (options, logger) => {
   if (options.outputStdout) {
     logger.success("Result:\n\n" + result);
   } else {
-    await writeFile2(options.outputPath, result);
+    await writeFile3(options.outputPath, result);
     logger.success(`Compiled to ${options.outputPath}`);
   }
 };
-var handler_default2 = compileHandler;
+var handler_default3 = compileHandler;
 
 // src/test/handler.ts
 var testHandler = async (options, logger) => {
@@ -945,11 +1137,16 @@ var testHandler = async (options, logger) => {
   }
   const state = await load_state_default(plan, opts, createNullLogger());
   const compiledPlan = await compile_default(plan, opts, logger);
-  const result = await execute_default(compiledPlan, state, opts, logger);
+  const result = await execute_default(
+    compiledPlan,
+    state,
+    opts,
+    logger
+  );
   logger.success(`Result: ${result.data.answer}`);
   return result;
 };
-var handler_default3 = testHandler;
+var handler_default4 = testHandler;
 
 // src/deploy/handler.ts
 import {
@@ -1002,33 +1199,33 @@ function mergeOverrides(config, options) {
 function pickFirst(...args) {
   return args.find((arg) => arg !== void 0 && arg !== null);
 }
-var handler_default4 = deployHandler;
+var handler_default5 = deployHandler;
 
 // src/docgen/handler.ts
-import { writeFile as writeFile3 } from "node:fs/promises";
+import { writeFile as writeFile4 } from "node:fs/promises";
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
-import path4 from "node:path";
+import path5 from "node:path";
 import { describePackage } from "@openfn/describe-package";
 import { getNameAndVersion as getNameAndVersion3 } from "@openfn/runtime";
 var RETRY_DURATION = 500;
 var RETRY_COUNT = 20;
 var TIMEOUT_MS = 1e3 * 60;
 var actualDocGen = (specifier) => describePackage(specifier, {});
-var ensurePath = (filePath) => mkdirSync(path4.dirname(filePath), { recursive: true });
-var generatePlaceholder = (path8) => {
-  writeFileSync(path8, `{ "loading": true, "timestamp": ${Date.now()}}`);
+var ensurePath = (filePath) => mkdirSync(path5.dirname(filePath), { recursive: true });
+var generatePlaceholder = (path9) => {
+  writeFileSync(path9, `{ "loading": true, "timestamp": ${Date.now()}}`);
 };
 var finish = (logger, resultPath) => {
   logger.success("Done! Docs can be found at:\n");
-  logger.print(`  ${path4.resolve(resultPath)}`);
+  logger.print(`  ${path5.resolve(resultPath)}`);
 };
-var generateDocs = async (specifier, path8, docgen, logger) => {
+var generateDocs = async (specifier, path9, docgen, logger) => {
   const result = await docgen(specifier);
-  await writeFile3(path8, JSON.stringify(result, null, 2));
-  finish(logger, path8);
-  return path8;
+  await writeFile4(path9, JSON.stringify(result, null, 2));
+  finish(logger, path9);
+  return path9;
 };
-var waitForDocs = async (docs, path8, logger, retryDuration = RETRY_DURATION) => {
+var waitForDocs = async (docs, path9, logger, retryDuration = RETRY_DURATION) => {
   try {
     if (docs.hasOwnProperty("loading")) {
       logger.info("Docs are being loaded by another process. Waiting.");
@@ -1040,19 +1237,19 @@ var waitForDocs = async (docs, path8, logger, retryDuration = RETRY_DURATION) =>
             clearInterval(i);
             reject(new Error("Timed out waiting for docs to load"));
           }
-          const updated = JSON.parse(readFileSync(path8, "utf8"));
+          const updated = JSON.parse(readFileSync(path9, "utf8"));
           if (!updated.hasOwnProperty("loading")) {
             logger.info("Docs found!");
             clearInterval(i);
-            resolve(path8);
+            resolve(path9);
           }
           count++;
         }, retryDuration);
       });
     } else {
-      logger.info(`Docs already written to cache at ${path8}`);
-      finish(logger, path8);
-      return path8;
+      logger.info(`Docs already written to cache at ${path9}`);
+      finish(logger, path9);
+      return path9;
     }
   } catch (e) {
     logger.error("Existing doc JSON corrupt. Aborting");
@@ -1069,42 +1266,44 @@ var docgenHandler = (options, logger, docgen = actualDocGen, retryDuration = RET
     process.exit(9);
   }
   logger.success(`Generating docs for ${specifier}`);
-  const path8 = `${repoDir}/docs/${specifier}.json`;
-  ensurePath(path8);
+  const path9 = `${repoDir}/docs/${specifier}.json`;
+  ensurePath(path9);
   const handleError = () => {
     logger.info("Removing placeholder");
-    rmSync(path8);
+    rmSync(path9);
   };
   try {
-    const existing = readFileSync(path8, "utf8");
+    const existing = readFileSync(path9, "utf8");
     const json = JSON.parse(existing);
     if (json && json.timeout && Date.now() - json.timeout >= TIMEOUT_MS) {
       logger.info(`Expired placeholder found. Removing.`);
-      rmSync(path8);
+      rmSync(path9);
       throw new Error("TIMEOUT");
     }
-    return waitForDocs(json, path8, logger, retryDuration);
+    return waitForDocs(json, path9, logger, retryDuration);
   } catch (e) {
     if (e.message !== "TIMEOUT") {
-      logger.info(`Docs JSON not found at ${path8}`);
+      logger.info(`Docs JSON not found at ${path9}`);
     }
     logger.debug("Generating placeholder");
-    generatePlaceholder(path8);
-    return generateDocs(specifier, path8, docgen, logger).catch((e2) => {
+    generatePlaceholder(path9);
+    return generateDocs(specifier, path9, docgen, logger).catch((e2) => {
       logger.error("Error generating documentation");
       logger.error(e2);
       handleError();
     });
   }
 };
-var handler_default5 = docgenHandler;
+var handler_default6 = docgenHandler;
 
 // src/docs/handler.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 import c from "chalk";
 import { getNameAndVersion as getNameAndVersion4, getLatestVersion } from "@openfn/runtime";
 var describeFn = (adaptorName, fn) => [
-  c.green(`## ${fn.name}(${fn.parameters.map(({ name }) => name).join(",")})`),
+  c.green(
+    `## ${fn.name}(${fn.parameters.map(({ name }) => name).join(",")})`
+  ),
   `${fn.description}`,
   c.green("### Usage Examples"),
   fn.examples.length ? fn.examples.map(({ code, caption }) => {
@@ -1123,7 +1322,9 @@ ${code}`;
 ].join("\n\n");
 var describeLib = (adaptorName, data) => c.green(`## ${adaptorName} ${data.version}`) + `
 
-${data.functions.map((fn) => `  ${c.yellow(fn.name)} (${fn.parameters.map((p) => p.name).join(", ")})`).sort().join("\n")}
+${data.functions.map(
+  (fn) => `  ${c.yellow(fn.name)} (${fn.parameters.map((p) => p.name).join(", ")})`
+).sort().join("\n")}
 `;
 var docsHandler = async (options, logger) => {
   const { adaptor, operation, repoDir } = options;
@@ -1137,7 +1338,7 @@ var docsHandler = async (options, logger) => {
     logger.success(`Showing docs for ${adaptorName} v${version}`);
   }
   logger.info("Generating/loading documentation...");
-  const path8 = await handler_default5(
+  const path9 = await handler_default6(
     {
       specifier: `${name}@${version}`,
       repoDir
@@ -1146,8 +1347,8 @@ var docsHandler = async (options, logger) => {
     createNullLogger()
   );
   let didError = false;
-  if (path8) {
-    const source = await readFile2(path8, "utf8");
+  if (path9) {
+    const source = await readFile3(path9, "utf8");
     const data = JSON.parse(source);
     let desc;
     if (operation) {
@@ -1180,13 +1381,13 @@ var docsHandler = async (options, logger) => {
     logger.error("Not found");
   }
 };
-var handler_default6 = docsHandler;
+var handler_default7 = docsHandler;
 
 // src/metadata/cache.ts
 import { createHash } from "node:crypto";
 import { readFileSync as readFileSync2 } from "node:fs";
-import path5 from "node:path";
-import { writeFile as writeFile4, mkdir } from "node:fs/promises";
+import path6 from "node:path";
+import { writeFile as writeFile5, mkdir as mkdir2 } from "node:fs/promises";
 var getPath = (repoDir, key) => `${repoDir}/meta/${key}.json`;
 var sortKeys = (obj) => {
   const newObj = {};
@@ -1216,8 +1417,8 @@ var get = (repoPath, key) => {
 };
 var set = async (repoPath, key, data) => {
   const fullPath = getPath(repoPath, key);
-  await mkdir(path5.dirname(fullPath), { recursive: true });
-  await writeFile4(fullPath, JSON.stringify(data));
+  await mkdir2(path6.dirname(fullPath), { recursive: true });
+  await writeFile5(fullPath, JSON.stringify(data));
 };
 var cache_default = { get, set, generateKey, getPath, sortKeys };
 
@@ -1301,10 +1502,10 @@ var metadataHandler = async (options, logger) => {
     process.exit(1);
   }
 };
-var handler_default7 = metadataHandler;
+var handler_default8 = metadataHandler;
 
 // src/pull/handler.ts
-import path6 from "path";
+import path7 from "path";
 import fs4 from "node:fs/promises";
 import {
   getConfig as getConfig2,
@@ -1316,7 +1517,9 @@ async function pullHandler(options, logger) {
   try {
     assert_path_default(options.projectId);
     const config = mergeOverrides2(await getConfig2(options.configPath), options);
-    logger.always("Downloading existing project state (as JSON) from the server.");
+    logger.always(
+      "Downloading existing project state (as JSON) from the server."
+    );
     const { data: project } = await getProject(config, options.projectId);
     if (!project) {
       logger.error("ERROR: Project not found.");
@@ -1328,12 +1531,10 @@ async function pullHandler(options, logger) {
     }
     const state = getStateFromProjectPayload(project);
     await fs4.writeFile(
-      path6.resolve(config.statePath),
+      path7.resolve(config.statePath),
       JSON.stringify(state, null, 2)
     );
-    logger.always(
-      "Downloading the project spec (as YAML) from the server."
-    );
+    logger.always("Downloading the project spec (as YAML) from the server.");
     const url2 = new URL(
       `api/provision/yaml?id=${options.projectId}`,
       config.endpoint
@@ -1353,7 +1554,7 @@ async function pullHandler(options, logger) {
       process.exitCode = 1;
       process.exit(1);
     }
-    const resolvedPath = path6.resolve(config.specPath);
+    const resolvedPath = path7.resolve(config.specPath);
     logger.debug("reading spec from", resolvedPath);
     await fs4.writeFile(resolvedPath, res.body);
     const spec = await getSpec(resolvedPath);
@@ -1382,11 +1583,11 @@ function mergeOverrides2(config, options) {
 function pickFirst2(...args) {
   return args.find((arg) => arg !== void 0 && arg !== null);
 }
-var handler_default8 = pullHandler;
+var handler_default9 = pullHandler;
 
 // src/util/print-versions.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-import path7 from "node:path";
+import path8 from "node:path";
 import url from "node:url";
 import { getNameAndVersion as getNameAndVersion5 } from "@openfn/runtime";
 import { mainSymbols } from "figures";
@@ -1398,7 +1599,7 @@ var { triangleRightSmall: t } = mainSymbols;
 var loadVersionFromPath = (adaptorPath) => {
   try {
     const pkg = JSON.parse(
-      readFileSync3(path7.resolve(adaptorPath, "package.json"), "utf8")
+      readFileSync3(path8.resolve(adaptorPath, "package.json"), "utf8")
     );
     return pkg.version;
   } catch (e) {
@@ -1431,7 +1632,7 @@ var printVersions = async (logger, options = {}, includeComponents = false) => {
     ...[NODE, CLI2, RUNTIME2, COMPILER2, adaptorName].map((s) => s.length)
   );
   const prefix = (str) => `         ${t} ${str.padEnd(longest + 4, " ")}`;
-  const dirname = path7.dirname(url.fileURLToPath(import.meta.url));
+  const dirname = path8.dirname(url.fileURLToPath(import.meta.url));
   const pkg = JSON.parse(readFileSync3(`${dirname}/../../package.json`, "utf8"));
   const { version, dependencies } = pkg;
   const compilerVersion = dependencies["@openfn/compiler"];
@@ -1471,14 +1672,15 @@ var print_versions_default = printVersions;
 
 // src/commands.ts
 var handlers = {
-  execute: handler_default,
-  compile: handler_default2,
-  test: handler_default3,
-  deploy: handler_default4,
-  docgen: handler_default5,
-  docs: handler_default6,
-  metadata: handler_default7,
-  pull: handler_default8,
+  apollo: handler_default,
+  execute: handler_default2,
+  compile: handler_default3,
+  test: handler_default4,
+  deploy: handler_default5,
+  docgen: handler_default6,
+  docs: handler_default7,
+  metadata: handler_default8,
+  pull: handler_default9,
   ["repo-clean"]: clean,
   ["repo-install"]: install,
   ["repo-pwd"]: pwd,
@@ -1507,7 +1709,7 @@ var parse = async (options, log) => {
       logger
     );
   }
-  if (!/^(pull|deploy|test|version)$/.test(options.command) && !options.repoDir) {
+  if (!/^(pull|deploy|test|version|apollo)$/.test(options.command) && !options.repoDir) {
     logger.warn(
       "WARNING: no repo module dir found! Using the default (/tmp/repo)"
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/cli",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "description": "CLI devtools for the openfn toolchain.",
   "engines": {
     "node": ">=18",
@@ -29,6 +29,7 @@
     "@types/node": "^18.15.13",
     "@types/rimraf": "^3.0.2",
     "@types/treeify": "^1.0.0",
+    "@types/ws": "^8.5.10",
     "@types/yargs": "^17.0.24",
     "ava": "5.3.1",
     "mock-fs": "^5.1.4",
@@ -44,12 +45,13 @@
     "figures": "^5.0.0",
     "rimraf": "^3.0.2",
     "treeify": "^1.1.0",
+    "ws": "^8.14.1",
     "yargs": "^17.7.2",
     "@openfn/compiler": "0.1.2",
+    "@openfn/deploy": "0.4.6",
     "@openfn/describe-package": "0.0.19",
     "@openfn/logger": "1.0.1",
-    "@openfn/runtime": "1.1.3",
-    "@openfn/deploy": "0.4.6"
+    "@openfn/runtime": "1.1.3"
   },
   "files": [
     "dist",