@openfn/cli 1.24.1 → 1.26.0

package/dist/index.js

@@ -368,7 +368,7 @@ var ignoreImports = {
   }
 };
 var getBaseDir = (opts2) => {
-  const basePath = opts2.path ?? ".";
+  const basePath = opts2.path ?? opts2.workspace ?? ".";
   if (/\.(jso?n?|ya?ml)$/.test(basePath)) {
     return nodePath.dirname(basePath);
   }
@@ -923,12 +923,27 @@ var alias = {
     description: "Environment name (eg staging, prod, branch)"
   }
 };
+var clean = {
+  name: "clean",
+  yargs: {
+    description: "Clean the working dir before checking out the new project",
+    default: false,
+    boolean: true
+  }
+};
 var dryRun2 = {
   name: "dryRun",
   yargs: {
     description: "Runs the command but does not commit any changes to disk or app"
   }
 };
+var format = {
+  name: "format",
+  yargs: {
+    hidden: true,
+    description: "The format to save the project as - state, yaml or json. Use this to download raw state files."
+  }
+};
 var removeUnmapped = {
   name: "remove-unmapped",
   yargs: {
@@ -1138,7 +1153,7 @@ var command_default9 = pullCommand;
 var repo = {
   command: "repo [subcommand]",
   describe: "Run commands on the module repo (install|clean)",
-  builder: (yargs2) => yargs2.command(clean).command(install).command(list).example("repo install -a http", "Install @openfn/language-http").example("repo clean", "Remove everything from the repo working dir")
+  builder: (yargs2) => yargs2.command(clean2).command(install).command(list).example("repo install -a http", "Install @openfn/language-http").example("repo clean", "Remove everything from the repo working dir")
 };
 var installOptions = [
   log,
@@ -1177,7 +1192,7 @@ var cleanOptions = [
     }
   }
 ];
-var clean = {
+var clean2 = {
   command: "clean",
   describe: "Removes all modules from the runtime module repo",
   handler: ensure("repo-clean", cleanOptions),
@@ -1225,18 +1240,24 @@ var command2 = {
 var version_default = command2;
 
 // src/projects/merge.ts
-import Project3, { Workspace as Workspace4 } from "@openfn/project";
+import Project3, { Workspace as Workspace5 } from "@openfn/project";
 
 // src/projects/checkout.ts
-import Project2, { Workspace as Workspace3 } from "@openfn/project";
+import Project2, { Workspace as Workspace4 } from "@openfn/project";
+import { rimraf as rimraf2 } from "rimraf";
+
+// src/projects/util.ts
 import { rimraf } from "rimraf";
-var options11 = [log, workspace];
+import { versionsEqual } from "@openfn/project";
+
+// src/projects/checkout.ts
+var options11 = [log, workspace, clean, force];
 var command3 = {
   command: "checkout <project>",
   describe: "Switch to a different OpenFn project in the same workspace",
   handler: ensure("project-checkout", options11),
   builder: (yargs2) => build(options11, yargs2).positional("project", {
-    describe: "The id, alias or UUID of the project to chcekout",
+    describe: "The id, alias or UUID of the project to checkout",
     demandOption: true
   })
 };
@@ -1277,7 +1298,7 @@ var command4 = {
 var merge_default = command4;
 
 // src/projects/fetch.ts
-import Project4, { Workspace as Workspace5 } from "@openfn/project";
+import Project4, { Workspace as Workspace6 } from "@openfn/project";
 var options13 = [
   alias,
   apiKey,
@@ -1291,7 +1312,8 @@ var options13 = [
   }),
   outputPath2,
   env2,
-  workspace
+  workspace,
+  format
 ];
 var command5 = {
   command: "fetch [project]",
@@ -1307,6 +1329,7 @@ var command5 = {
 var fetch_default = command5;
 
 // src/projects/pull.ts
+import { Workspace as Workspace7 } from "@openfn/project";
 var options14 = [
   alias,
   env2,
@@ -1335,7 +1358,7 @@ var command6 = {
 };
 
 // src/projects/deploy.ts
-import Project5 from "@openfn/project";
+import Project5, { versionsEqual as versionsEqual2, Workspace as Workspace8 } from "@openfn/project";
 import c2 from "chalk";
 var options15 = [
   env2,
@@ -1351,6 +1374,7 @@ var options15 = [
 ];
 var command7 = {
   command: "deploy",
+  aliases: "push",
   describe: `Deploy the checked out project to a Lightning Instance`,
   builder: (yargs2) => build(options15, yargs2).positional("project", {
     describe: "The UUID, local id or local alias of the project to deploy to"

package/dist/process/runner.js

@@ -133,14 +133,14 @@ var callApollo = async (apolloBaseUrl, serviceName, payload, logger) => {
     });
   });
 };
-var loadPayload = async (logger, path17) => {
-  if (!path17) {
+var loadPayload = async (logger, path18) => {
+  if (!path18) {
     logger.warn("No JSON payload provided");
     logger.warn("Most apollo services require JSON to be uploaded");
     return {};
   }
-  if (path17.endsWith(".json")) {
-    const str = await readFile(path17, "utf8");
+  if (path18.endsWith(".json")) {
+    const str = await readFile(path18, "utf8");
     const json = JSON.parse(str);
     logger.debug("Loaded JSON payload");
     return json;
@@ -190,22 +190,31 @@ var createNullLogger = () => createLogger2(void 0, { log: { default: "none" } })
 import fs from "node:fs";
 import path2 from "node:path";
 import { rmdir } from "node:fs/promises";
-var getCachePath = async (plan, options8, stepId) => {
-  const { baseDir } = options8;
-  const { name } = plan.workflow;
-  const basePath = `${baseDir}/.cli-cache/${name}`;
+var CACHE_DIR = ".cli-cache";
+var getCachePath = (options8, workflowName, stepId) => {
+  const { baseDir, cachePath } = options8;
+  if (cachePath) {
+    if (stepId) {
+      return path2.resolve(cachePath, `${stepId.replace(/ /, "-")}.json`);
+    }
+    return path2.resolve(cachePath);
+  }
+  const basePath = path2.resolve(
+    baseDir ?? process.cwd(),
+    `${CACHE_DIR}/${workflowName}`
+  );
   if (stepId) {
-    return path2.resolve(`${basePath}/${stepId.replace(/ /, "-")}.json`);
+    return `${basePath}/${stepId.replace(/ /, "-")}.json`;
   }
-  return path2.resolve(basePath);
+  return basePath;
 };
-var ensureGitIgnore = (options8) => {
+var ensureGitIgnore = (options8, cachePath) => {
   if (!options8._hasGitIgnore) {
-    const ignorePath = path2.resolve(
-      options8.baseDir,
-      ".cli-cache",
-      ".gitignore"
-    );
+    let root = cachePath;
+    while (root.length > 1 && !root.endsWith(CACHE_DIR)) {
+      root = path2.dirname(root);
+    }
+    const ignorePath = path2.resolve(root, ".gitignore");
     try {
       fs.accessSync(ignorePath);
     } catch (e) {
@@ -216,15 +225,15 @@ var ensureGitIgnore = (options8) => {
 };
 var saveToCache = async (plan, stepId, output, options8, logger) => {
   if (options8.cacheSteps) {
-    const cachePath = await getCachePath(plan, options8, stepId);
+    const cachePath = await getCachePath(options8, plan.workflow.name, stepId);
     fs.mkdirSync(path2.dirname(cachePath), { recursive: true });
-    ensureGitIgnore(options8);
+    ensureGitIgnore(options8, path2.dirname(cachePath));
     logger.info(`Writing ${stepId} output to ${cachePath}`);
     fs.writeFileSync(cachePath, JSON.stringify(output));
   }
 };
 var clearCache = async (plan, options8, logger) => {
-  const cacheDir = await getCachePath(plan, options8);
+  const cacheDir = await getCachePath(options8, plan.workflow?.name);
   try {
     await rmdir(cacheDir, { recursive: true });
     logger.info(`Cleared cache at ${cacheDir}`);
@@ -267,13 +276,13 @@ var execute_default = async (plan, input, opts, logger) => {
 };
 function parseAdaptors(plan) {
   const extractInfo = (specifier) => {
-    const [module, path17] = specifier.split("=");
+    const [module, path18] = specifier.split("=");
     const { name, version } = getNameAndVersion(module);
     const info = {
       name
     };
-    if (path17) {
-      info.path = path17;
+    if (path18) {
+      info.path = path18;
     }
     if (version) {
       info.version = version;
@@ -583,10 +592,10 @@ var stripVersionSpecifier = (specifier) => {
   return specifier;
 };
 var resolveSpecifierPath = async (pattern, repoDir, log2) => {
-  const [specifier, path17] = pattern.split("=");
-  if (path17) {
-    log2.debug(`Resolved ${specifier} to path: ${path17}`);
-    return path17;
+  const [specifier, path18] = pattern.split("=");
+  if (path18) {
+    log2.debug(`Resolved ${specifier} to path: ${path18}`);
+    return path18;
   }
   const repoPath = await getModulePath(specifier, repoDir, log2);
   if (repoPath) {
@@ -605,12 +614,12 @@ var loadTransformOptions = async (opts, log2) => {
       let exports;
       const [specifier] = adaptorInput.split("=");
       log2.debug(`Trying to preload types for ${specifier}`);
-      const path17 = await resolveSpecifierPath(adaptorInput, opts.repoDir, log2);
-      if (path17) {
+      const path18 = await resolveSpecifierPath(adaptorInput, opts.repoDir, log2);
+      if (path18) {
         try {
-          exports = await preloadAdaptorExports(path17, log2);
+          exports = await preloadAdaptorExports(path18, log2);
         } catch (e) {
-          log2.error(`Failed to load adaptor typedefs from path ${path17}`);
+          log2.error(`Failed to load adaptor typedefs from path ${path18}`);
           log2.error(e);
         }
       }
@@ -685,7 +694,11 @@ var load_state_default = async (plan, opts, log2, start) => {
       const upstreamStepId = getUpstreamStepId(plan, start);
       if (upstreamStepId) {
         log2.debug(`Input step for "${start}" is "${upstreamStepId}"`);
-        const cachedStatePath = await getCachePath(plan, opts, upstreamStepId);
+        const cachedStatePath = await getCachePath(
+          opts,
+          plan.workflow.name,
+          upstreamStepId
+        );
         log2.debug("Loading cached state from", cachedStatePath);
         try {
           await fs2.access(cachedStatePath);
@@ -830,8 +843,8 @@ var map_adaptors_to_monorepo_default = mapAdaptorsToMonorepo;
 // src/util/resolve-path.ts
 import nodepath from "node:path";
 import os from "node:os";
-var resolve_path_default = (path17, root) => {
-  return path17.startsWith("~") ? path17.replace(`~`, os.homedir) : nodepath.resolve(root ?? "", path17);
+var resolve_path_default = (path18, root) => {
+  return path18.startsWith("~") ? path18.replace(`~`, os.homedir) : nodepath.resolve(root ?? "", path18);
 };
 
 // src/util/load-plan.ts
@@ -857,6 +870,7 @@ var loadPlan = async (options8, logger) => {
     };
     options8.credentials ??= workspace2.getConfig().credentials;
     options8.collectionsEndpoint ??= proj.openfn?.endpoint;
+    options8.cachePath ??= workspace2.workflowsPath + `/${name}/${CACHE_DIR}`;
   }
   if (options8.path && /ya?ml$/.test(options8.path)) {
     const content = await fs3.readFile(path4.resolve(options8.path), "utf-8");
@@ -886,7 +900,10 @@ var loadPlan = async (options8, logger) => {
       defaultName
     );
   } else {
-    return loadXPlan({ workflow: workflowObj }, options8, logger, defaultName);
+    const { id, start, options: o, ...w } = workflowObj;
+    const opts = { ...o, start };
+    const plan = { id, workflow: w, options: opts };
+    return loadXPlan(plan, options8, logger, defaultName);
   }
 };
 var load_plan_default = loadPlan;
@@ -1131,8 +1148,8 @@ var loadXPlan = async (plan, options8, logger, defaultName = "") => {
 };
 
 // src/util/assert-path.ts
-var assert_path_default = (path17) => {
-  if (!path17) {
+var assert_path_default = (path18) => {
+  if (!path18) {
     console.error("ERROR: no path provided!");
     console.error("\nUsage:");
     console.error("  open path/to/job");
@@ -1195,7 +1212,8 @@ var assertStepStructure = (step, index) => {
     "state",
     "configuration",
     "linker",
-    "openfn"
+    "openfn",
+    "enabled"
   ];
   for (const key in step) {
     if (!allowedKeys.includes(key)) {
@@ -1370,7 +1388,10 @@ var executeHandler = async (options8, logger) => {
     const result = await execute_default(finalPlan, state, options8, logger);
     if (options8.cacheSteps) {
       logger.success(
-        "Cached output written to ./cli-cache (see info logs for details)"
+        `Cached output written to ${getCachePath(
+          options8,
+          plan.workflow.name
+        )} (see info logs for details)`
       );
     }
     await serialize_output_default(options8, result, logger);
@@ -1761,8 +1782,10 @@ import {
 } from "@openfn/deploy";
 
 // src/projects/deploy.ts
-import Project from "@openfn/project";
+import Project, { versionsEqual as versionsEqual2, Workspace as Workspace3 } from "@openfn/project";
 import c2 from "chalk";
+import { writeFile as writeFile6 } from "node:fs/promises";
+import path10 from "node:path";
 
 // src/util/ensure-log-opts.ts
 var defaultLoggerOptions = {
@@ -1956,12 +1979,27 @@ var alias = {
     description: "Environment name (eg staging, prod, branch)"
   }
 };
+var clean2 = {
+  name: "clean",
+  yargs: {
+    description: "Clean the working dir before checking out the new project",
+    default: false,
+    boolean: true
+  }
+};
 var dryRun = {
   name: "dryRun",
   yargs: {
     description: "Runs the command but does not commit any changes to disk or app"
   }
 };
+var format = {
+  name: "format",
+  yargs: {
+    hidden: true,
+    description: "The format to save the project as - state, yaml or json. Use this to download raw state files."
+  }
+};
 var removeUnmapped = {
   name: "remove-unmapped",
   yargs: {
@@ -2013,6 +2051,8 @@ var CLIError = class extends Error {
 };
 
 // src/projects/util.ts
+import { rimraf } from "rimraf";
+import { versionsEqual } from "@openfn/project";
 var loadAppAuthConfig = (options8, logger) => {
   const { OPENFN_API_KEY, OPENFN_ENDPOINT } = process.env;
   const config2 = {
@@ -2036,22 +2076,22 @@ var ensureExt = (filePath, ext) => {
   return filePath;
 };
 var getSerializePath = (project, workspacePath, outputPath2) => {
-  const outputRoot = resolve_path_default(outputPath2 || workspacePath);
+  const outputRoot = resolve_path_default(outputPath2 || workspacePath || ".");
   const projectsDir = project?.config.dirs.projects ?? ".projects";
-  return outputPath2 ?? `${outputRoot}/${projectsDir}/${project.qname}`;
+  return outputPath2 ?? `${outputRoot}/${projectsDir}/${project?.qname}`;
 };
 var serialize = async (project, outputPath2, formatOverride, dryRun2 = false) => {
   const root = path9.dirname(outputPath2);
   await mkdir3(root, { recursive: true });
-  const format = formatOverride ?? project.config?.formats.project;
-  const output = project?.serialize("project", { format });
+  const format2 = formatOverride ?? project.config?.formats.project;
+  const output = format2 === "state" ? project?.serialize("state", { format: "json" }) : project?.serialize("project", { format: format2 });
   const maybeWriteFile = (filePath, output2) => {
     if (!dryRun2) {
       return writeFile5(filePath, output2);
     }
   };
   let finalPath;
-  if (format === "yaml") {
+  if (format2 === "yaml") {
     finalPath = ensureExt(outputPath2, "yaml");
     await maybeWriteFile(finalPath, output);
   } else {
@@ -2060,10 +2100,10 @@ var serialize = async (project, outputPath2, formatOverride, dryRun2 = false) =>
   }
   return finalPath;
 };
-var getLightningUrl = (endpoint2, path17 = "", snapshots2) => {
+var getLightningUrl = (endpoint2, path18 = "", snapshots2) => {
   const params = new URLSearchParams();
   snapshots2?.forEach((snapshot) => params.append("snapshots[]", snapshot));
-  return new URL(`/api/provision/${path17}?${params.toString()}`, endpoint2);
+  return new URL(`/api/provision/${path18}?${params.toString()}`, endpoint2);
 };
 async function fetchProject(endpoint2, apiKey2, projectId, logger, snapshots2) {
   const url2 = getLightningUrl(endpoint2, projectId, snapshots2);
@@ -2107,9 +2147,16 @@ async function deployProject(endpoint2, apiKey2, state, logger) {
       body: JSON.stringify(state)
     });
     if (!response.ok) {
-      const body = await response.json();
+      logger?.error(`Deploy failed with code `, response.status);
       logger?.error("Failed to deploy project:");
-      logger?.error(JSON.stringify(body, null, 2));
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.match("application/json ")) {
+        const body = await response.json();
+        logger?.error(JSON.stringify(body, null, 2));
+      } else {
+        const content = await response.text();
+        logger?.error(content);
+      }
       throw new CLIError(
         `Failed to deploy project ${state.name}: ${response.status}`
       );
@@ -2132,6 +2179,58 @@ var DeployError = class extends Error {
     super(message);
   }
 };
+async function tidyWorkflowDir(currentProject, incomingProject, dryRun2 = false) {
+  if (!currentProject || !incomingProject) {
+    return [];
+  }
+  const currentFiles = currentProject.serialize("fs");
+  const newFiles = incomingProject.serialize("fs");
+  const toRemove = [];
+  for (const path18 in currentFiles) {
+    if (!newFiles[path18]) {
+      toRemove.push(path18);
+    }
+  }
+  if (!dryRun2) {
+    await rimraf(toRemove);
+  }
+  return toRemove.sort();
+}
+var updateForkedFrom = (proj) => {
+  proj.cli.forked_from = proj.workflows.reduce((obj, wf) => {
+    if (wf.history.length) {
+      obj[wf.id] = wf.history.at(-1);
+    }
+    return obj;
+  }, {});
+  return proj;
+};
+var findLocallyChangedWorkflows = async (workspace2, project, ifNoForkedFrom = "assume-diverged") => {
+  const { forked_from } = workspace2.activeProject ?? {};
+  if (!forked_from || Object.keys(forked_from).length === 0) {
+    if (ifNoForkedFrom === "assume-ok") {
+      return [];
+    }
+    return project.workflows.map((w) => w.id);
+  }
+  const changedWorkflows = [];
+  for (const workflow2 of project.workflows) {
+    const currentHash = workflow2.getVersionHash();
+    const forkedHash = forked_from[workflow2.id];
+    if (forkedHash === void 0) {
+      changedWorkflows.push(workflow2.id);
+    } else if (!versionsEqual(currentHash, forkedHash)) {
+      changedWorkflows.push(workflow2.id);
+    }
+  }
+  const currentWorkflowIds = new Set(project.workflows.map((w) => w.id));
+  for (const workflowId in forked_from) {
+    if (!currentWorkflowIds.has(workflowId)) {
+      changedWorkflows.push(workflowId);
+    }
+  }
+  return changedWorkflows;
+};
 
 // src/util/command-builders.ts
 import c from "chalk";
@@ -2195,6 +2294,7 @@ var options = [
 var printProjectName = (project) => `${project.id} (${project.openfn?.uuid || "<no UUID>"})`;
 var command = {
   command: "deploy",
+  aliases: "push",
   describe: `Deploy the checked out project to a Lightning Instance`,
   builder: (yargs) => build(options, yargs).positional("project", {
     describe: "The UUID, local id or local alias of the project to deploy to"
@@ -2204,14 +2304,34 @@ var command = {
   ),
   handler: ensure("project-deploy", options)
 };
+var hasRemoteDiverged = (local, remote, workflows = []) => {
+  let diverged = null;
+  const refs = local.cli.forked_from ?? {};
+  const filteredWorkflows = workflows.length ? local.workflows.filter((w) => workflows.includes(w.id)) : local.workflows;
+  for (const wf of filteredWorkflows) {
+    if (wf.id in refs) {
+      const forkedVersion = refs[wf.id];
+      const remoteVersion = remote.getWorkflow(wf.id)?.history.at(-1);
+      if (!versionsEqual2(forkedVersion, remoteVersion)) {
+        diverged ??= [];
+        diverged.push(wf.id);
+      }
+    } else {
+    }
+  }
+  return diverged;
+};
 async function handler(options8, logger) {
   logger.warn(
     "WARNING: the project deploy command is in BETA and may not be stable. Use cautiously on production projects."
   );
   const config2 = loadAppAuthConfig(options8, logger);
   logger.info("Attempting to load checked-out project from workspace");
+  const ws = new Workspace3(options8.workspace || ".");
+  const { alias: alias2 } = ws.getActiveProject();
   const localProject = await Project.from("fs", {
-    root: options8.workspace || "."
+    root: options8.workspace || ".",
+    alias: alias2
   });
   logger.success(`Loaded local project ${printProjectName(localProject)}`);
   let remoteProject;
@@ -2238,33 +2358,61 @@ Your local project (${localProject.uuid}) has a different UUID to the remote pro
 Pass --force to override this error and deploy anyway.`);
     return false;
   }
-  const diffs = reportDiff(remoteProject, localProject, logger);
+  const locallyChangedWorkflows = await findLocallyChangedWorkflows(
+    ws,
+    localProject
+  );
+  const diffs = reportDiff(
+    localProject,
+    remoteProject,
+    locallyChangedWorkflows,
+    logger
+  );
   if (!diffs.length) {
     logger.success("Nothing to deploy");
     return;
   }
-  if (!localProject.canMergeInto(remoteProject)) {
-    if (!options8.force) {
-      logger.error(`Error: Projects have diverged!
+  const skipVersionTest = remoteProject.workflows.find(
+    (wf) => wf.history.length === 0
+  );
+  if (skipVersionTest) {
+    logger.warn(
+      "Skipping compatibility check as no local version history detected"
+    );
+    logger.warn("Pushing these changes may overwrite changes made to the app");
+  } else {
+    const divergentWorkflows = hasRemoteDiverged(
+      localProject,
+      remoteProject,
+      locallyChangedWorkflows
+    );
+    if (divergentWorkflows) {
+      logger.warn(
+        `The following workflows have diverged: ${divergentWorkflows}`
+      );
+      if (!options8.force) {
+        logger.error(`Error: Projects have diverged!
 
-The remote project has been edited since the local project was branched. Changes may be lost.
+  The remote project has been edited since the local project was branched. Changes may be lost.
 
-Pass --force to override this error and deploy anyway.`);
-      return;
+  Pass --force to override this error and deploy anyway.`);
+        return;
+      } else {
+        logger.warn(
+          "Remote project has diverged from local project! Pushing anyway as -f passed"
+        );
+      }
     } else {
-      logger.warn(
-        "Remote project has not diverged from local project! Pushing anyway as -f passed"
+      logger.info(
+        "Remote project has not diverged from local project - it is safe to deploy \u{1F389}"
       );
     }
-  } else {
-    logger.info(
-      "Remote project has not diverged from local project - it is safe to deploy \u{1F389}"
-    );
   }
   logger.info("Merging changes into remote project");
   const merged = Project.merge(localProject, remoteProject, {
     mode: "replace",
-    force: true
+    force: true,
+    onlyUpdated: true
   });
   const state = merged.serialize("state", {
     format: "json"
@@ -2298,14 +2446,20 @@ Pass --force to override this error and deploy anyway.`);
       },
       merged.config
     );
+    updateForkedFrom(finalProject);
+    const configData = finalProject.generateConfig();
+    await writeFile6(
+      path10.resolve(options8.workspace, configData.path),
+      configData.content
+    );
     const finalOutputPath = getSerializePath(localProject, options8.workspace);
-    logger.debug("Updating local project at ", finalOutputPath);
-    await serialize(finalProject, finalOutputPath);
+    const fullFinalPath = await serialize(finalProject, finalOutputPath);
+    logger.debug("Updated local project at ", fullFinalPath);
+    logger.success("Updated project  at", config2.endpoint);
   }
-  logger.success("Updated project at", config2.endpoint);
 }
-var reportDiff = (local, remote, logger) => {
-  const diffs = remote.diff(local);
+var reportDiff = (local, remote, locallyChangedWorkflows, logger) => {
+  const diffs = remote.diff(local, locallyChangedWorkflows);
   if (diffs.length === 0) {
     logger.info("No workflow changes detected");
     return diffs;
@@ -2392,30 +2546,30 @@ function pickFirst(...args) {
 var handler_default6 = deployHandler;
 
 // src/docgen/handler.ts
-import { writeFile as writeFile6 } from "node:fs/promises";
+import { writeFile as writeFile7 } from "node:fs/promises";
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
-import path10 from "node:path";
+import path11 from "node:path";
 import { describePackage } from "@openfn/describe-package";
 import { getNameAndVersion as getNameAndVersion4 } 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(path10.dirname(filePath), { recursive: true });
-var generatePlaceholder = (path17) => {
-  writeFileSync(path17, `{ "loading": true, "timestamp": ${Date.now()}}`);
+var ensurePath = (filePath) => mkdirSync(path11.dirname(filePath), { recursive: true });
+var generatePlaceholder = (path18) => {
+  writeFileSync(path18, `{ "loading": true, "timestamp": ${Date.now()}}`);
 };
 var finish = (logger, resultPath) => {
   logger.success("Done! Docs can be found at:\n");
-  logger.print(`  ${path10.resolve(resultPath)}`);
+  logger.print(`  ${path11.resolve(resultPath)}`);
 };
-var generateDocs = async (specifier, path17, docgen, logger) => {
+var generateDocs = async (specifier, path18, docgen, logger) => {
   const result = await docgen(specifier);
-  await writeFile6(path17, JSON.stringify(result, null, 2));
-  finish(logger, path17);
-  return path17;
+  await writeFile7(path18, JSON.stringify(result, null, 2));
+  finish(logger, path18);
+  return path18;
 };
-var waitForDocs = async (docs, path17, logger, retryDuration = RETRY_DURATION) => {
+var waitForDocs = async (docs, path18, logger, retryDuration = RETRY_DURATION) => {
   try {
     if (docs.hasOwnProperty("loading")) {
       logger.info("Docs are being loaded by another process. Waiting.");
@@ -2427,19 +2581,19 @@ var waitForDocs = async (docs, path17, logger, retryDuration = RETRY_DURATION) =
             clearInterval(i);
             reject(new Error("Timed out waiting for docs to load"));
           }
-          const updated = JSON.parse(readFileSync(path17, "utf8"));
+          const updated = JSON.parse(readFileSync(path18, "utf8"));
           if (!updated.hasOwnProperty("loading")) {
             logger.info("Docs found!");
             clearInterval(i);
-            resolve(path17);
+            resolve(path18);
           }
           count++;
         }, retryDuration);
       });
     } else {
-      logger.info(`Docs already written to cache at ${path17}`);
-      finish(logger, path17);
-      return path17;
+      logger.info(`Docs already written to cache at ${path18}`);
+      finish(logger, path18);
+      return path18;
     }
   } catch (e) {
     logger.error("Existing doc JSON corrupt. Aborting");
@@ -2456,28 +2610,28 @@ var docgenHandler = (options8, logger, docgen = actualDocGen, retryDuration = RE
     process.exit(9);
   }
   logger.success(`Generating docs for ${specifier}`);
-  const path17 = `${repoDir}/docs/${specifier}.json`;
-  ensurePath(path17);
+  const path18 = `${repoDir}/docs/${specifier}.json`;
+  ensurePath(path18);
   const handleError2 = () => {
     logger.info("Removing placeholder");
-    rmSync(path17);
+    rmSync(path18);
   };
   try {
-    const existing = readFileSync(path17, "utf8");
+    const existing = readFileSync(path18, "utf8");
     const json = JSON.parse(existing);
     if (json && json.timeout && Date.now() - json.timeout >= TIMEOUT_MS) {
       logger.info(`Expired placeholder found. Removing.`);
-      rmSync(path17);
+      rmSync(path18);
       throw new Error("TIMEOUT");
     }
-    return waitForDocs(json, path17, logger, retryDuration);
+    return waitForDocs(json, path18, logger, retryDuration);
   } catch (e) {
     if (e.message !== "TIMEOUT") {
-      logger.info(`Docs JSON not found at ${path17}`);
+      logger.info(`Docs JSON not found at ${path18}`);
     }
     logger.debug("Generating placeholder");
-    generatePlaceholder(path17);
-    return generateDocs(specifier, path17, docgen, logger).catch((e2) => {
+    generatePlaceholder(path18);
+    return generateDocs(specifier, path18, docgen, logger).catch((e2) => {
       logger.error("Error generating documentation");
       logger.error(e2);
       handleError2();
@@ -2528,7 +2682,7 @@ var docsHandler = async (options8, logger) => {
     logger.success(`Showing docs for ${adaptorName} v${version}`);
   }
   logger.info("Generating/loading documentation...");
-  const path17 = await handler_default7(
+  const path18 = await handler_default7(
     {
       specifier: `${name}@${version}`,
       repoDir
@@ -2537,8 +2691,8 @@ var docsHandler = async (options8, logger) => {
     createNullLogger()
   );
   let didError = false;
-  if (path17) {
-    const source = await readFile5(path17, "utf8");
+  if (path18) {
+    const source = await readFile5(path18, "utf8");
     const data = JSON.parse(source);
     let desc;
     if (operation) {
@@ -2576,13 +2730,13 @@ var handler_default8 = docsHandler;
 // src/metadata/cache.ts
 import { getNameAndVersion as getNameAndVersion6 } from "@openfn/runtime";
 import { createHash } from "node:crypto";
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile7, readdir, rm } from "node:fs/promises";
-import path11 from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile8, readdir, rm } from "node:fs/promises";
+import path12 from "node:path";
 var UNSUPPORTED_FILE_NAME = "unsupported.json";
 var getCachePath2 = (repoDir, key) => {
-  const base = path11.join(repoDir, "meta");
+  const base = path12.join(repoDir, "meta");
   if (key) {
-    return path11.join(base, key.endsWith(".json") ? key : `${key}.json`);
+    return path12.join(base, key.endsWith(".json") ? key : `${key}.json`);
   }
   return base;
 };
@@ -2624,8 +2778,8 @@ var get2 = async (repoPath, key) => {
 };
 var set2 = async (repoPath, key, result) => {
   const p = getCachePath2(repoPath, key);
-  await mkdir4(path11.dirname(p), { recursive: true });
-  await writeFile7(p, JSON.stringify(result));
+  await mkdir4(path12.dirname(p), { recursive: true });
+  await writeFile8(p, JSON.stringify(result));
 };
 var getUnsupportedCachePath = (repoDir) => {
   return getCachePath2(repoDir, UNSUPPORTED_FILE_NAME);
@@ -2683,8 +2837,8 @@ var markAdaptorAsUnsupported = async (adaptorSpecifier, repoDir) => {
       majorMinor: parsed.majorMinor,
       timestamp: Date.now()
     };
-    await mkdir4(path11.dirname(cachePath), { recursive: true });
-    await writeFile7(cachePath, JSON.stringify(cache, null, 2));
+    await mkdir4(path12.dirname(cachePath), { recursive: true });
+    await writeFile8(cachePath, JSON.stringify(cache, null, 2));
   }
 };
 
@@ -2805,7 +2959,7 @@ var metadataHandler = async (options8, logger) => {
 var handler_default9 = metadataHandler;
 
 // src/pull/handler.ts
-import path14 from "path";
+import path15 from "path";
 import fs5 from "node:fs/promises";
 import {
   getConfig as getConfig2,
@@ -2815,9 +2969,13 @@ import {
   syncRemoteSpec
 } from "@openfn/deploy";
 
+// src/projects/pull.ts
+import { Workspace as Workspace6 } from "@openfn/project";
+
 // src/projects/fetch.ts
-import path12 from "node:path";
-import Project2, { Workspace as Workspace2 } from "@openfn/project";
+import path13 from "node:path";
+import Project2, { Workspace as Workspace4 } from "@openfn/project";
+import { writeFile as writeFile9 } from "node:fs/promises";
 var options2 = [
   alias,
   apiKey,
@@ -2831,7 +2989,8 @@ var options2 = [
   }),
   outputPath,
   env,
-  workspace
+  workspace,
+  format
 ];
 var command2 = {
   command: "fetch [project]",
@@ -2845,28 +3004,73 @@ var command2 = {
   handler: ensure("project-fetch", options2)
 };
 var printProjectName2 = (project) => `${project.qname} (${project.id})`;
-var handler2 = async (options8, logger) => {
+var fetchV1 = async (options8, logger) => {
   const workspacePath = options8.workspace ?? process.cwd();
   logger.debug("Using workspace at", workspacePath);
-  const workspace2 = new Workspace2(workspacePath, logger, false);
-  const { outputPath: outputPath2 } = options8;
-  const localTargetProject = await resolveOutputProject(
-    workspace2,
-    options8,
+  const workspace2 = new Workspace4(workspacePath, logger, false);
+  const localProject = workspace2.get(options8.project);
+  if (localProject) {
+    logger.debug(
+      `Resolved "${options8.project}" to local project ${printProjectName2(
+        localProject
+      )}`
+    );
+  } else {
+    logger.debug(
+      `Failed to resolve "${options8.project}" to local project. Will send request to app anyway.`
+    );
+  }
+  const config2 = loadAppAuthConfig(options8, logger);
+  const { data } = await fetchProject(
+    options8.endpoint ?? localProject?.openfn?.endpoint,
+    config2.apiKey,
+    localProject?.uuid ?? options8.project,
     logger
   );
+  const finalOutputPath = getSerializePath(
+    localProject,
+    options8.workspace,
+    options8.outputPath
+  );
+  logger.success(`Fetched project file to ${finalOutputPath}`);
+  await writeFile9(finalOutputPath, JSON.stringify(data, null, 2));
+  return data;
+};
+var handler2 = async (options8, logger) => {
+  if (options8.format === "state") {
+    return fetchV1(options8, logger);
+  }
+  return fetchV2(options8, logger);
+};
+var fetchV2 = async (options8, logger) => {
+  const workspacePath = options8.workspace ?? process.cwd();
+  logger.debug("Using workspace at", workspacePath);
+  const workspace2 = new Workspace4(workspacePath, logger, false);
+  const { outputPath: outputPath2 } = options8;
   const remoteProject = await fetchRemoteProject(workspace2, options8, logger);
-  ensureTargetCompatible(options8, remoteProject, localTargetProject);
+  if (!options8.alias && remoteProject.sandbox?.parentId) {
+    options8.alias = remoteProject.id;
+    remoteProject.cli.alias = options8.alias;
+    logger.debug("Defaulting alias to sandbox id", options8.alias);
+  }
+  if (!options8.force && options8.format !== "state") {
+    const localTargetProject = await resolveOutputProject(
+      workspace2,
+      options8,
+      logger
+    );
+    ensureTargetCompatible(options8, remoteProject, localTargetProject);
+  }
   const finalOutputPath = getSerializePath(
     remoteProject,
     workspacePath,
     outputPath2
   );
-  let format = void 0;
+  let format2 = options8.format;
   if (outputPath2) {
-    const ext = path12.extname(outputPath2).substring(1);
+    const ext = path13.extname(outputPath2).substring(1);
     if (ext.length) {
-      format = ext;
+      format2 = ext;
     }
     if (options8.alias) {
       logger.warn(
@@ -2874,10 +3078,12 @@ var handler2 = async (options8, logger) => {
       );
     }
   }
-  await serialize(remoteProject, finalOutputPath, format);
-  logger.success(
-    `Fetched project file to ${finalOutputPath}.${format ?? "yaml"}`
+  const finalPathWithExt = await serialize(
+    remoteProject,
+    finalOutputPath,
+    format2
   );
+  logger.success(`Fetched project file to ${finalPathWithExt}`);
   return remoteProject;
 };
 async function resolveOutputProject(workspace2, options8, logger) {
@@ -2930,7 +3136,7 @@ async function fetchRemoteProject(workspace2, options8, logger) {
     logger.debug(
       `Resolved ${options8.project} to UUID ${projectUUID} from local project ${printProjectName2(
         localProject
-      )}}`
+      )}`
     );
   }
   const projectEndpoint = localProject?.openfn?.endpoint ?? config2.endpoint;
@@ -2984,40 +3190,33 @@ To ignore this error and override the local file, pass --force (-f)
       delete error.stack;
       throw error;
     }
-    const hasAnyHistory = remoteProject.workflows.find(
-      (w) => w.workflow.history?.length
-    );
-    const skipVersionCheck = options8.force || // The user forced the checkout
-    !hasAnyHistory;
-    if (!skipVersionCheck && !remoteProject.canMergeInto(localProject)) {
-      throw new Error("Error! An incompatible project exists at this location");
-    }
   }
 }
 
 // src/projects/checkout.ts
-import Project3, { Workspace as Workspace3 } from "@openfn/project";
-import path13 from "path";
+import Project3, { Workspace as Workspace5 } from "@openfn/project";
+import path14 from "path";
 import fs4 from "fs";
-import { rimraf } from "rimraf";
-var options3 = [log, workspace];
+import { rimraf as rimraf2 } from "rimraf";
+var options3 = [log, workspace, clean2, force];
 var command3 = {
   command: "checkout <project>",
   describe: "Switch to a different OpenFn project in the same workspace",
   handler: ensure("project-checkout", options3),
   builder: (yargs) => build(options3, yargs).positional("project", {
-    describe: "The id, alias or UUID of the project to chcekout",
+    describe: "The id, alias or UUID of the project to checkout",
     demandOption: true
   })
 };
 var handler3 = async (options8, logger) => {
   const projectIdentifier = options8.project;
   const workspacePath = options8.workspace ?? process.cwd();
-  const workspace2 = new Workspace3(workspacePath, logger);
+  const workspace2 = new Workspace5(workspacePath, logger);
   const { project: _, ...config2 } = workspace2.getConfig();
+  const currentProject = workspace2.getActiveProject();
   let switchProject;
   if (/\.(yaml|json)$/.test(projectIdentifier)) {
-    const filePath = projectIdentifier.startsWith("/") ? projectIdentifier : path13.join(workspacePath, projectIdentifier);
+    const filePath = projectIdentifier.startsWith("/") ? projectIdentifier : path14.join(workspacePath, projectIdentifier);
     logger.debug("Loading project from path ", filePath);
     switchProject = await Project3.from("path", filePath, config2);
   } else {
@@ -3028,14 +3227,51 @@ var handler3 = async (options8, logger) => {
       `Project with id ${projectIdentifier} not found in the workspace`
     );
   }
-  await rimraf(path13.join(workspacePath, config2.workflowRoot ?? "workflows"));
+  try {
+    const localProject = await Project3.from("fs", {
+      root: options8.workspace || "."
+    });
+    logger.success(`Loaded local project ${localProject.alias}`);
+    const changed = await findLocallyChangedWorkflows(
+      workspace2,
+      localProject,
+      "assume-ok"
+    );
+    if (changed.length && !options8.force) {
+      logger.break();
+      logger.warn(
+        "WARNING: detected changes on your currently checked-out project"
+      );
+      logger.warn(
+        `Changes may be lost by checking out ${localProject.alias} right now`
+      );
+      logger.warn(`Pass --force or -f to override this warning and continue`);
+      const e = new Error(
+        `The currently checked out project has diverged! Changes may be lost`
+      );
+      delete e.stack;
+      throw e;
+    }
+  } catch (e) {
+    if (e.message.match("ENOENT")) {
+      logger.debug("No openfn.yaml found locally: skipping divergence test");
+    } else {
+      throw e;
+    }
+  }
+  if (options8.clean) {
+    await rimraf2(workspace2.workflowsPath);
+  } else {
+    await tidyWorkflowDir(currentProject, switchProject);
+  }
+  updateForkedFrom(switchProject);
   const files = switchProject.serialize("fs");
   for (const f in files) {
     if (files[f]) {
-      fs4.mkdirSync(path13.join(workspacePath, path13.dirname(f)), {
+      fs4.mkdirSync(path14.join(workspacePath, path14.dirname(f)), {
         recursive: true
       });
-      fs4.writeFileSync(path13.join(workspacePath, f), files[f]);
+      fs4.writeFileSync(path14.join(workspacePath, f), files[f]);
     } else {
       logger.warn("WARNING! No content for file", f);
     }
@@ -3071,11 +3307,30 @@ var command4 = {
   handler: ensure("project-pull", options4)
 };
 async function handler4(options8, logger) {
+  ensureProjectId(options8, logger);
   await handler2(options8, logger);
   logger.success(`Downloaded latest project version`);
   await handler3(options8, logger);
   logger.success(`Checked out project locally`);
 }
+var ensureProjectId = (options8, logger) => {
+  if (!options8.project) {
+    logger?.debug(
+      "No project ID specified: looking up checked out project in Workspace"
+    );
+    const ws = new Workspace6(options8.workspace);
+    if (ws.activeProject) {
+      options8.project = ws.activeProject.uuid;
+      logger?.info(
+        `Project id not provided: will default to ${options8.project}`
+      );
+    } else {
+      throw new Error(
+        "Project not provided: specify a project UUID, id or alias"
+      );
+    }
+  }
+};
 var pull_default = handler4;
 
 // src/pull/handler.ts
@@ -3136,7 +3391,7 @@ async function pullHandler(options8, logger) {
       process.exitCode = 1;
       process.exit(1);
     }
-    const resolvedPath = path14.resolve(config2.specPath);
+    const resolvedPath = path15.resolve(config2.specPath);
     logger.debug("reading spec from", resolvedPath);
     const updatedSpec = await syncRemoteSpec(
       await res.text(),
@@ -3145,7 +3400,7 @@ async function pullHandler(options8, logger) {
       logger
     );
     await fs5.writeFile(
-      path14.resolve(config2.statePath),
+      path15.resolve(config2.statePath),
       JSON.stringify(state, null, 2)
     );
     await fs5.writeFile(resolvedPath, updatedSpec);
@@ -3190,7 +3445,7 @@ __export(projects_exports, {
 });
 
 // src/projects/list.ts
-import { Workspace as Workspace4 } from "@openfn/project";
+import { Workspace as Workspace7 } from "@openfn/project";
 var options5 = [log, workspace];
 var command5 = {
   command: "list [project-path]",
@@ -3203,7 +3458,7 @@ var handler5 = async (options8, logger) => {
   logger.info("Searching for projects in workspace at:");
   logger.info(" ", options8.workspace);
   logger.break();
-  const workspace2 = new Workspace4(options8.workspace);
+  const workspace2 = new Workspace7(options8.workspace);
   if (!workspace2.valid) {
     throw new Error("No OpenFn projects found");
   }
@@ -3221,7 +3476,7 @@ ${project.workflows.map((w) => "    - " + w.id).join("\n")}`;
 }
 
 // src/projects/version.ts
-import { Workspace as Workspace5 } from "@openfn/project";
+import { Workspace as Workspace8 } from "@openfn/project";
 var options6 = [workflow, workspace, workflowMappings];
 var command6 = {
   command: "version [workflow]",
@@ -3230,7 +3485,7 @@ var command6 = {
   builder: (yargs) => build(options6, yargs)
 };
 var handler6 = async (options8, logger) => {
-  const workspace2 = new Workspace5(options8.workspace);
+  const workspace2 = new Workspace8(options8.workspace);
   if (!workspace2.valid) {
     logger.error("Command was run in an invalid openfn workspace");
     return;
@@ -3265,8 +3520,8 @@ ${final}`);
 };
 
 // src/projects/merge.ts
-import Project5, { Workspace as Workspace6 } from "@openfn/project";
-import path15 from "node:path";
+import Project5, { Workspace as Workspace9 } from "@openfn/project";
+import path16 from "node:path";
 import fs6 from "node:fs/promises";
 var options7 = [
   removeUnmapped,
@@ -3301,14 +3556,14 @@ var command7 = {
 };
 var handler7 = async (options8, logger) => {
   const workspacePath = options8.workspace;
-  const workspace2 = new Workspace6(workspacePath);
+  const workspace2 = new Workspace9(workspacePath);
   if (!workspace2.valid) {
     logger.error("Command was run in an invalid openfn workspace");
     return;
   }
   let targetProject;
   if (options8.base) {
-    const basePath = path15.resolve(options8.base);
+    const basePath = path16.resolve(options8.base);
     logger.debug("Loading target project from path", basePath);
     targetProject = await Project5.from("path", basePath);
   } else {
@@ -3322,7 +3577,7 @@ var handler7 = async (options8, logger) => {
   const sourceProjectIdentifier = options8.project;
   let sourceProject;
   if (/\.(ya?ml|json)$/.test(sourceProjectIdentifier)) {
-    const filePath = path15.join(workspacePath, sourceProjectIdentifier);
+    const filePath = path16.join(workspacePath, sourceProjectIdentifier);
     logger.debug("Loading source project from path ", filePath);
     sourceProject = await Project5.from("path", filePath);
   } else {
@@ -3385,7 +3640,7 @@ var handler7 = async (options8, logger) => {
 
 // src/util/print-versions.ts
 import { readFileSync as readFileSync2 } from "node:fs";
-import path16 from "node:path";
+import path17 from "node:path";
 import url from "node:url";
 import { getNameAndVersion as getNameAndVersion7 } from "@openfn/runtime";
 import { mainSymbols } from "figures";
@@ -3397,7 +3652,7 @@ var { triangleRightSmall: t } = mainSymbols;
 var loadVersionFromPath = (adaptorPath) => {
   try {
     const pkg = JSON.parse(
-      readFileSync2(path16.resolve(adaptorPath, "package.json"), "utf8")
+      readFileSync2(path17.resolve(adaptorPath, "package.json"), "utf8")
     );
     return pkg.version;
   } catch (e) {
@@ -3432,7 +3687,7 @@ var printVersions = async (logger, options8 = {}, includeComponents = false) =>
     ...[NODE, CLI2, RUNTIME2, COMPILER2, longestAdaptorName].map((s) => s.length)
   );
   const prefix = (str) => `         ${t} ${str.padEnd(longest + 4, " ")}`;
-  const dirname3 = path16.dirname(url.fileURLToPath(import.meta.url));
+  const dirname3 = path17.dirname(url.fileURLToPath(import.meta.url));
   const pkg = JSON.parse(readFileSync2(`${dirname3}/../../package.json`, "utf8"));
   const { version, dependencies } = pkg;
   const compilerVersion = dependencies["@openfn/compiler"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/cli",
-  "version": "1.24.1",
+  "version": "1.26.0",
   "description": "CLI devtools for the OpenFn toolchain",
   "engines": {
     "node": ">=18",
@@ -33,6 +33,7 @@
     "@types/ws": "^8.18.1",
     "@types/yargs": "^17.0.33",
     "ava": "5.3.1",
+    "lodash-es": "^4.17.21",
     "mock-fs": "^5.5.0",
     "tslib": "^2.8.1",
     "tsup": "^7.2.0",
@@ -49,13 +50,13 @@
     "undici": "7.12.0",
     "ws": "^8.18.3",
     "yargs": "^17.7.2",
-    "@openfn/describe-package": "0.1.5",
-    "@openfn/lexicon": "^1.4.0",
     "@openfn/compiler": "1.2.2",
-    "@openfn/logger": "1.1.1",
     "@openfn/deploy": "0.11.5",
-    "@openfn/project": "^0.12.0",
-    "@openfn/runtime": "1.8.2"
+    "@openfn/logger": "1.1.1",
+    "@openfn/lexicon": "^1.4.1",
+    "@openfn/project": "^0.13.0",
+    "@openfn/runtime": "1.8.3",
+    "@openfn/describe-package": "0.1.5"
   },
   "files": [
     "dist",