@openfn/project 0.12.0 → 0.13.0

package/README.md

@@ -91,3 +91,5 @@ Reference:
 parent(propName=propValue,x=y)-child
 a-b # can comment here to
 ```
+
+Use special names `webhook` and `cron` to create trigger nodes (when converting into app state, the difference between a step and a trigger becomes important).

package/dist/index.d.ts

@@ -29,7 +29,19 @@ type WorkflowDiff = {
  * // Shows how staging has diverged from main
  * ```
  */
-declare function diff(a: Project, b: Project): WorkflowDiff[];
+declare function diff(a: Project, b: Project, workflows?: string[]): WorkflowDiff[];
+
+/**
+ *
+ * Compare two version hashes
+ * Ignores the source specifier (if present)
+ */
+declare const match: (a: string, b: string) => boolean;
+type HashOptions = {
+    source?: string;
+    sha?: boolean;
+};
+declare const generateHash: (workflow: Workflow, { source, sha }?: HashOptions) => string;
 
 type WithMeta<T> = T & {
     openfn?: l.NodeMeta;
@@ -45,6 +57,7 @@ declare class Workflow {
     get steps(): WithMeta<l.Job & l.Trigger>[];
     get start(): string | undefined;
     set start(s: string);
+    get history(): string[];
     _buildIndex(): void;
     set(id: string, props: Partial<l.Job | l.StepEdge>): this;
     get(id: string): WithMeta<l.Step | l.Trigger | l.StepEdge>;
@@ -56,7 +69,7 @@ declare class Workflow {
     getUUID(id: string): string;
     toJSON(): Object;
     getUUIDMap(): Record<string, string>;
-    getVersionHash(): string;
+    getVersionHash(options?: HashOptions): string;
     pushHistory(versionHash: string): void;
     canMergeInto(target: Workflow): boolean;
 }
@@ -75,6 +88,7 @@ type FromFsConfig = {
     root: string;
     config?: Partial<l.WorkspaceConfig>;
     logger?: Logger;
+    alias?: string;
 };
 
 type SerializedProject = Omit<Partial<l.Project>, 'workflows'> & {
@@ -94,7 +108,16 @@ type MergeProjectOptions = {
     workflowMappings: Record<string, string>;
     removeUnmapped: boolean;
     force: boolean;
+    /**
+     * If mode is sandbox, basically only content will be merged and all metadata/settings/options/config is ignored
+     * If mode is replace, all properties on the source will override the target (including UUIDs, name)
+     */
     mode: typeof SANDBOX_MERGE | typeof REPLACE_MERGE;
+    /**
+     * If true, only workflows that have changed in the source
+     * will be merged.
+     */
+    onlyUpdated: boolean;
 };
 
 declare class Workspace {
@@ -108,6 +131,8 @@ declare class Workspace {
     constructor(workspacePath: string, logger?: Logger, validate?: boolean);
     loadProject(): void;
     list(): Project[];
+    get projectsPath(): string;
+    get workflowsPath(): string;
     /** Get a project by its alias, id or UUID. Can also include a UUID */
     get(nameyThing: string): Project | null;
     getProjectPath(id: string): string | undefined;
@@ -130,6 +155,7 @@ type UUIDMap = {
 type CLIMeta = {
     version?: number;
     alias?: string;
+    forked_from?: Record<string, string>;
 };
 declare class Project {
     /** Human readable project name. This corresponds to the label in Lightning */
@@ -160,6 +186,7 @@ declare class Project {
     constructor(data?: Partial<l__default.Project>, meta?: Partial<l__default.WorkspaceConfig> & CLIMeta);
     /** Local alias for the project. Comes from the file name. Not shared with Lightning. */
     get alias(): string;
+    set alias(value: string);
     get uuid(): string | undefined;
     get host(): string | undefined;
     setConfig(config: Partial<WorkspaceConfig>): void;
@@ -174,8 +201,17 @@ declare class Project {
      * Returns a map of ids:uuids for everything in the project
      */
     getUUIDMap(): UUIDMap;
-    diff(project: Project): WorkflowDiff[];
+    diff(project: Project, workflows?: string[]): WorkflowDiff[];
     canMergeInto(target: Project): boolean;
+    /**
+     * Generates the contents of the openfn.yaml file,
+     * plus its file path
+     */
+    generateConfig(): {
+        path: string;
+        content: string;
+    };
+    clone(): Project;
 }
 
 declare function yamlToJson(y: string): any;
@@ -187,6 +223,8 @@ type GenerateWorkflowOptions = {
     printErrors: boolean;
     uuidMap?: Record<string, string>;
     openfnUuid: boolean;
+    /** If true, will set up a version hash in the history array */
+    history: boolean;
 };
 type GenerateProjectOptions = GenerateWorkflowOptions & {
     uuidMap: Array<Record<string, string>>;
@@ -199,4 +237,4 @@ type GenerateProjectOptions = GenerateWorkflowOptions & {
 declare function generateWorkflow(def: string, options?: Partial<GenerateWorkflowOptions>): Workflow;
 declare function generateProject(name: string, workflowDefs: string[], options?: Partial<GenerateProjectOptions>): Project;
 
-export { DiffType, WorkflowDiff, Workspace, Project as default, diff, generateProject, generateWorkflow, jsonToYaml, yamlToJson };
+export { DiffType, WorkflowDiff, Workspace, Project as default, diff, generateProject, generateHash as generateVersionHash, generateWorkflow, jsonToYaml, match as versionsEqual, yamlToJson };

package/dist/index.js

@@ -14,65 +14,261 @@ function slugify(text) {
 
 // src/util/version.ts
 import crypto from "node:crypto";
+import { get } from "lodash-es";
+
+// src/serialize/to-app-state.ts
+import { pick, omitBy, isNil, sortBy } from "lodash-es";
+import { randomUUID } from "node:crypto";
+
+// src/util/rename-keys.ts
+function renameKeys(props = {}, keyMap) {
+  return Object.fromEntries(
+    Object.entries(props).map(([key, value]) => [
+      keyMap[key] ? keyMap[key] : key,
+      value
+    ])
+  );
+}
+
+// src/util/yaml.ts
+import yaml from "yaml";
+function yamlToJson(y) {
+  const doc = yaml.parseDocument(y);
+  return doc.toJS();
+}
+function jsonToYaml(json) {
+  if (typeof json === "string") {
+    json = JSON.parse(json);
+  }
+  const doc = new yaml.Document(json);
+  return yaml.stringify(doc, null, 2);
+}
+
+// src/serialize/to-app-state.ts
+var defaultJobProps = {
+  // TODO why does the provisioner throw if these keys are not set?
+  // Ok, 90% of jobs will have a credenial, but it's still optional right?
+  keychain_credential_id: null,
+  project_credential_id: null
+};
+function to_app_state_default(project, options = {}) {
+  const {
+    uuid,
+    endpoint,
+    env,
+    id,
+    fetched_at,
+    ...rest
+  } = project.openfn ?? {};
+  const state = omitBy(
+    pick(project, ["name", "description", "collections"]),
+    isNil
+  );
+  state.id = uuid;
+  Object.assign(state, rest, project.options);
+  state.project_credentials = project.credentials ?? [];
+  state.workflows = project.workflows.map(mapWorkflow).reduce((obj, wf) => {
+    obj[slugify(wf.name ?? wf.id)] = wf;
+    return obj;
+  }, {});
+  const shouldReturnYaml = options.format === "yaml" || !options.format && project.config.formats.project === "yaml";
+  if (shouldReturnYaml) {
+    return jsonToYaml(state);
+  }
+  return state;
+}
+var mapWorkflow = (workflow) => {
+  if (workflow instanceof Workflow_default) {
+    workflow = workflow.toJSON();
+  }
+  const { uuid, ...originalOpenfnProps } = workflow.openfn ?? {};
+  const wfState = {
+    ...originalOpenfnProps,
+    id: workflow.openfn?.uuid ?? randomUUID(),
+    jobs: {},
+    triggers: {},
+    edges: {},
+    lock_version: workflow.openfn?.lock_version ?? null
+    // TODO needs testing
+  };
+  if (workflow.name) {
+    wfState.name = workflow.name;
+  }
+  const lookup = workflow.steps.reduce((obj, next) => {
+    if (!next.openfn?.uuid) {
+      next.openfn ??= {};
+      next.openfn.uuid = randomUUID();
+    }
+    obj[next.id] = next.openfn.uuid;
+    return obj;
+  }, {});
+  sortBy(workflow.steps, "name").forEach((s) => {
+    let isTrigger = false;
+    let node;
+    if (s.type) {
+      isTrigger = true;
+      node = {
+        type: s.type ?? "webhook",
+        // this is mostly for tests
+        enabled: s.enabled,
+        ...renameKeys(s.openfn, { uuid: "id" })
+      };
+      wfState.triggers[node.type] = node;
+    } else {
+      node = omitBy(pick(s, ["name", "adaptor"]), isNil);
+      const { uuid: uuid2, ...otherOpenFnProps } = s.openfn ?? {};
+      node.id = uuid2;
+      if (s.expression) {
+        node.body = s.expression;
+      }
+      if (typeof s.configuration === "string" && !s.configuration.endsWith(".json")) {
+        otherOpenFnProps.project_credential_id = s.configuration;
+      }
+      Object.assign(node, defaultJobProps, otherOpenFnProps);
+      wfState.jobs[s.id ?? slugify(s.name)] = node;
+    }
+    Object.keys(s.next ?? {}).forEach((next) => {
+      const rules = s.next[next];
+      const { uuid: uuid2, ...otherOpenFnProps } = rules.openfn ?? {};
+      const e = {
+        id: uuid2 ?? randomUUID(),
+        target_job_id: lookup[next],
+        enabled: !rules.disabled,
+        source_trigger_id: null
+        // lightning complains if this isn't set, even if its falsy :(
+      };
+      Object.assign(e, otherOpenFnProps);
+      if (isTrigger) {
+        e.source_trigger_id = node.id;
+      } else {
+        e.source_job_id = node.id;
+      }
+      if (rules.label) {
+        e.condition_label = rules.label;
+      }
+      if (rules.condition) {
+        if (typeof rules.condition === "boolean") {
+          e.condition_type = rules.condition ? "always" : "never";
+        } else if (rules.condition.match(
+          /^(always|never|on_job_success|on_job_failure)$/
+        )) {
+          e.condition_type = rules.condition;
+        } else {
+          e.condition_type = "js_expression";
+          e.condition_expression = rules.condition;
+        }
+      }
+      wfState.edges[`${s.id}->${next}`] = e;
+    });
+  });
+  wfState.edges = Object.keys(wfState.edges).sort(
+    (a, b) => `${wfState.edges[a].id}`.localeCompare("" + wfState.edges[b].id)
+  ).reduce((obj, key) => {
+    obj[key] = wfState.edges[key];
+    return obj;
+  }, {});
+  return wfState;
+};
+
+// src/util/version.ts
 var SHORT_HASH_LENGTH = 12;
 function isDefined(v) {
   return v !== void 0 && v !== null;
 }
-var generateHash = (workflow, source = "cli") => {
+var parse = (version) => {
+  if (version.match(":")) {
+    const [source, hash] = version.split(":");
+    return { source, hash };
+  }
+  return { hash: version };
+};
+var match = (a, b) => {
+  return parse(a).hash === parse(b).hash;
+};
+var generateHash = (workflow, { source = "cli", sha = true } = {}) => {
   const parts = [];
-  const wfKeys = ["name", "credentials"].sort();
+  const wfState = mapWorkflow(workflow);
+  const wfKeys = ["name", "positions"].sort();
   const stepKeys = [
     "name",
-    "adaptors",
     "adaptor",
-    // there's both adaptor & adaptors key in steps somehow
-    "expression",
-    "configuration",
-    // assumes a string credential id
-    "expression"
-    // TODO need to model trigger types in this, which I think are currently ignored
+    "keychain_credential_id",
+    "project_credential_id",
+    "body"
   ].sort();
+  const triggerKeys = ["type", "cron_expression", "enabled"].sort();
   const edgeKeys = [
-    "condition",
+    "name",
+    // generated
     "label",
-    "disabled"
-    // This feels more like an option - should be excluded?
+    "condition_type",
+    "condition_label",
+    "condition_expression",
+    "enabled"
   ].sort();
   wfKeys.forEach((key) => {
-    if (isDefined(workflow[key])) {
-      parts.push(key, serializeValue(workflow[key]));
+    const value = get(workflow, key);
+    if (isDefined(value)) {
+      parts.push(serializeValue(value));
     }
   });
-  const steps = (workflow.steps || []).slice().sort((a, b) => {
-    const aName = a.name ?? "";
-    const bName = b.name ?? "";
-    return aName.localeCompare(bName);
+  for (const triggerId in wfState.triggers) {
+    const trigger = wfState.triggers[triggerId];
+    triggerKeys.forEach((key) => {
+      const value = get(trigger, key);
+      if (isDefined(value)) {
+        parts.push(serializeValue(value));
+      }
+    });
+  }
+  const steps = Object.values(wfState.jobs).sort((a, b) => {
+    const aName = a.name ?? a.id ?? "";
+    const bName = b.name ?? b.id ?? "";
+    return aName.toLowerCase().localeCompare(bName.toLowerCase());
   });
   for (const step of steps) {
     stepKeys.forEach((key) => {
-      if (isDefined(step[key])) {
-        parts.push(key, serializeValue(step[key]));
+      const value = get(step, key);
+      if (isDefined(value)) {
+        parts.push(serializeValue(value));
       }
     });
-    if (step.next && Array.isArray(step.next)) {
-      const steps2 = step.next.slice();
-      steps2.slice().sort((a, b) => {
-        const aLabel = a.label || "";
-        const bLabel = b.label || "";
-        return aLabel.localeCompare(bLabel);
-      });
-      for (const edge of step.next) {
-        edgeKeys.forEach((key) => {
-          if (isDefined(edge[key])) {
-            parts.push(key, serializeValue(edge[key]));
-          }
-        });
+  }
+  const uuidMap = {};
+  for (const t in wfState.triggers) {
+    const uuid = wfState.triggers[t].id;
+    uuidMap[uuid] = wfState.triggers[t];
+    wfState.triggers[t].name = wfState.triggers[t].type;
+  }
+  for (const j in wfState.jobs) {
+    const uuid = wfState.jobs[j].id;
+    uuidMap[uuid] = wfState.jobs[j];
+  }
+  const edges = Object.values(wfState.edges).map((edge) => {
+    const source2 = uuidMap[edge.source_trigger_id ?? edge.source_job_id];
+    const target = uuidMap[edge.target_job_id];
+    edge.name = `${source2.name ?? source2.id}-${target.name ?? target.id}`;
+    return edge;
+  }).sort((a, b) => {
+    const aName = a.name ?? "";
+    const bName = b.name ?? "";
+    return aName.localeCompare(bName);
+  });
+  for (const edge of edges) {
+    edgeKeys.forEach((key) => {
+      const value = get(edge, key);
+      if (isDefined(value)) {
+        parts.push(serializeValue(value));
       }
-    }
+    });
   }
   const str = parts.join("");
-  const hash = crypto.createHash("sha256").update(str).digest("hex");
-  return `${source}:${hash.substring(0, SHORT_HASH_LENGTH)}`;
+  if (sha) {
+    const hash = crypto.createHash("sha256").update(str).digest("hex");
+    return `${source}:${hash.substring(0, SHORT_HASH_LENGTH)}`;
+  } else {
+    return `${source}:${str}`;
+  }
 };
 function serializeValue(val) {
   if (typeof val === "object") {
@@ -104,7 +300,7 @@ var Workflow = class {
       // uuid to ids
     };
     this.workflow = clone(workflow);
-    this.workflow.history = workflow.history?.length ? workflow.history : [];
+    this.workflow.history = workflow.history ?? [];
     const {
       id,
       name,
@@ -137,6 +333,9 @@ var Workflow = class {
   set start(s) {
     this.workflow.start = s;
   }
+  get history() {
+    return this.workflow.history ?? [];
+  }
   _buildIndex() {
     for (const step of this.workflow.steps) {
       const s = step;
@@ -168,7 +367,10 @@ var Workflow = class {
   }
   // Get properties on any step or edge by id or uuid
   get(id) {
-    const item = this.index.edges[id] || this.index.steps[id];
+    if (id in this.index.id) {
+      id = this.index.id[id];
+    }
+    let item = this.index.edges[id] || this.index.steps[id];
     if (!item) {
       throw new Error(`step/edge with id "${id}" does not exist in workflow`);
     }
@@ -230,8 +432,8 @@ var Workflow = class {
   getUUIDMap() {
     return this.index.uuid;
   }
-  getVersionHash() {
-    return generateHash(this);
+  getVersionHash(options) {
+    return generateHash(this, options);
   }
   pushHistory(versionHash) {
     this.workflow.history?.push(versionHash);
@@ -254,155 +456,6 @@ __export(serialize_exports, {
   state: () => to_app_state_default
 });
 
-// src/serialize/to-app-state.ts
-import { pick, omitBy, isNil, sortBy } from "lodash-es";
-import { randomUUID } from "node:crypto";
-
-// src/util/rename-keys.ts
-function renameKeys(props = {}, keyMap) {
-  return Object.fromEntries(
-    Object.entries(props).map(([key, value]) => [
-      keyMap[key] ? keyMap[key] : key,
-      value
-    ])
-  );
-}
-
-// src/util/yaml.ts
-import yaml from "yaml";
-function yamlToJson(y) {
-  const doc = yaml.parseDocument(y);
-  return doc.toJS();
-}
-function jsonToYaml(json) {
-  if (typeof json === "string") {
-    json = JSON.parse(json);
-  }
-  const doc = new yaml.Document(json);
-  return yaml.stringify(doc, null, 2);
-}
-
-// src/serialize/to-app-state.ts
-var defaultJobProps = {
-  // TODO why does the provisioner throw if these keys are not set?
-  // Ok, 90% of jobs will have a credenial, but it's still optional right?
-  keychain_credential_id: null,
-  project_credential_id: null
-};
-function to_app_state_default(project, options = {}) {
-  const {
-    uuid,
-    endpoint,
-    env,
-    id,
-    fetched_at,
-    ...rest
-  } = project.openfn ?? {};
-  const state = omitBy(
-    pick(project, ["name", "description", "collections"]),
-    isNil
-  );
-  state.id = uuid;
-  Object.assign(state, rest, project.options);
-  state.project_credentials = project.credentials ?? [];
-  state.workflows = project.workflows.map(mapWorkflow).reduce((obj, wf) => {
-    obj[slugify(wf.name ?? wf.id)] = wf;
-    return obj;
-  }, {});
-  const shouldReturnYaml = options.format === "yaml" || !options.format && project.config.formats.project === "yaml";
-  if (shouldReturnYaml) {
-    return jsonToYaml(state);
-  }
-  return state;
-}
-var mapWorkflow = (workflow) => {
-  if (workflow instanceof Workflow_default) {
-    workflow = workflow.toJSON();
-  }
-  const { uuid, ...originalOpenfnProps } = workflow.openfn ?? {};
-  const wfState = {
-    ...originalOpenfnProps,
-    id: workflow.openfn?.uuid ?? randomUUID(),
-    jobs: {},
-    triggers: {},
-    edges: {},
-    lock_version: workflow.openfn?.lock_version ?? null
-    // TODO needs testing
-  };
-  if (workflow.name) {
-    wfState.name = workflow.name;
-  }
-  const lookup = workflow.steps.reduce((obj, next) => {
-    if (!next.openfn?.uuid) {
-      next.openfn ??= {};
-      next.openfn.uuid = randomUUID();
-    }
-    obj[next.id] = next.openfn.uuid;
-    return obj;
-  }, {});
-  sortBy(workflow.steps, "name").forEach((s) => {
-    let isTrigger = false;
-    let node;
-    if (s.type && !s.expression) {
-      isTrigger = true;
-      node = {
-        type: s.type,
-        ...renameKeys(s.openfn, { uuid: "id" })
-      };
-      wfState.triggers[node.type] = node;
-    } else {
-      node = omitBy(pick(s, ["name", "adaptor"]), isNil);
-      const { uuid: uuid2, ...otherOpenFnProps } = s.openfn ?? {};
-      node.id = uuid2;
-      if (s.expression) {
-        node.body = s.expression;
-      }
-      if (typeof s.configuration === "string" && !s.configuration.endsWith(".json")) {
-        otherOpenFnProps.project_credential_id = s.configuration;
-      }
-      Object.assign(node, defaultJobProps, otherOpenFnProps);
-      wfState.jobs[s.id ?? slugify(s.name)] = node;
-    }
-    Object.keys(s.next ?? {}).forEach((next) => {
-      const rules = s.next[next];
-      const { uuid: uuid2, ...otherOpenFnProps } = rules.openfn ?? {};
-      const e = {
-        id: uuid2 ?? randomUUID(),
-        target_job_id: lookup[next],
-        enabled: !rules.disabled,
-        source_trigger_id: null
-        // lightning complains if this isn't set, even if its falsy :(
-      };
-      Object.assign(e, otherOpenFnProps);
-      if (isTrigger) {
-        e.source_trigger_id = node.id;
-      } else {
-        e.source_job_id = node.id;
-      }
-      if (rules.condition) {
-        if (typeof rules.condition === "boolean") {
-          e.condition_type = rules.condition ? "always" : "never";
-        } else if (rules.condition.match(
-          /^(always|never|on_job_success|on_job_failure)$/
-        )) {
-          e.condition_type = rules.condition;
-        } else {
-          e.condition_type = "js_expression";
-          e.condition_expression = rules.condition;
-        }
-      }
-      wfState.edges[`${s.id}->${next}`] = e;
-    });
-  });
-  wfState.edges = Object.keys(wfState.edges).sort(
-    (a, b) => `${wfState.edges[a].id}`.localeCompare("" + wfState.edges[b].id)
-  ).reduce((obj, key) => {
-    obj[key] = wfState.edges[key];
-    return obj;
-  }, {});
-  return wfState;
-};
-
 // src/serialize/to-fs.ts
 import nodepath from "path";
 import { omit } from "lodash-es";
@@ -432,6 +485,9 @@ var extractConfig = (source, format) => {
   if (source.name) {
     project.name = source.name;
   }
+  if (source.cli.forked_from && Object.keys(source.cli.forked_from).length) {
+    project.forked_from = source.cli.forked_from;
+  }
   const workspace = {
     ...source.config
   };
@@ -587,10 +643,13 @@ import { omitBy as omitBy3, isNil as isNil4 } from "lodash-es";
 // src/util/omit-nil.ts
 import { omitBy as omitBy2, isNil as isNil3 } from "lodash-es";
 var omitNil = (obj, key) => {
-  if (obj[key]) {
+  if (key && obj[key]) {
     obj[key] = omitBy2(obj[key], isNil3);
+  } else {
+    return omitBy2(obj, isNil3);
   }
 };
+var omit_nil_default = omitNil;
 var tidyOpenfn = (obj) => omitNil(obj, "openfn");
 
 // src/serialize/to-project.ts
@@ -707,7 +766,7 @@ var mapEdge = (edge) => {
     e.condition = edge.condition_type;
   }
   if (edge.condition_label) {
-    e.name = edge.condition_label;
+    e.label = edge.condition_label;
   }
   if (edge.id) {
     e.openfn = {
@@ -728,7 +787,7 @@ var mapWorkflow2 = (workflow) => {
     mapped.id = slugify(workflow.name);
   }
   Object.values(workflow.triggers).forEach((trigger) => {
-    const { type, ...otherProps } = trigger;
+    const { type, enabled, ...otherProps } = trigger;
     if (!mapped.start) {
       mapped.start = type;
     }
@@ -738,6 +797,7 @@ var mapWorkflow2 = (workflow) => {
     mapped.steps.push({
       id: type,
       type,
+      enabled,
       openfn: renameKeys(otherProps, { id: "uuid" }),
       next: connectedEdges.reduce((obj, edge) => {
         const target = Object.values(jobs).find(
@@ -829,16 +889,19 @@ import path3 from "node:path";
 import { glob } from "glob";
 import { omit as omit2 } from "lodash-es";
 var parseProject = async (options) => {
-  const { root, logger } = options;
+  const { root, logger, alias } = options;
   const { type, content } = findWorkspaceFile(root);
   const context = loadWorkspaceFile(content, type);
   const config = buildConfig(options.config ?? context.workspace);
   const proj = {
     id: context.project?.id,
     name: context.project?.name,
-    openfn: omit2(context.project, ["id"]),
+    openfn: omit2(context.project, ["id", "forked_from"]),
     config,
-    workflows: []
+    workflows: [],
+    cli: omit_nil_default({
+      forked_from: context.project.forked_from
+    })
   };
   const workflowDir = config.workflowRoot ?? config.dirs?.workflows ?? "workflows";
   const fileType = config.formats?.workflow ?? "yaml";
@@ -888,7 +951,10 @@ var parseProject = async (options) => {
       continue;
     }
   }
-  return new Project(proj, context.workspace);
+  return new Project(proj, {
+    alias,
+    ...context.workspace
+  });
 };
 
 // src/util/uuid.ts
@@ -934,7 +1000,7 @@ function baseMerge(target, source, sourceKeys, assigns = {}) {
   return assign(target, { ...pickedSource, ...assigns });
 }
 
-// src/merge/merge-node.ts
+// src/merge/merge-workflow.ts
 var clone2 = (obj) => JSON.parse(JSON.stringify(obj));
 function mergeWorkflows(source, target, mappings) {
   const targetNodes = {};
@@ -979,6 +1045,7 @@ function mergeWorkflows(source, target, mappings) {
   return {
     ...target,
     ...newSource,
+    history: source.history ?? target.history,
     openfn: {
       ...target.openfn,
       ...source.openfn,
@@ -1239,6 +1306,26 @@ function getDuplicates(arr) {
   return Array.from(duplicates);
 }
 
+// src/util/find-changed-workflows.ts
+var find_changed_workflows_default = (project) => {
+  const base = project.cli.forked_from ?? project.workflows.reduce((obj, wf) => {
+    if (wf.history.length) {
+      obj[wf.id] = wf.history.at(-1);
+    }
+    return obj;
+  }, {});
+  const changed = [];
+  for (const wf of project.workflows) {
+    if (wf.id in base) {
+      const hash = generateHash(wf);
+      if (hash !== base[wf.id]) {
+        changed.push(wf);
+      }
+    }
+  }
+  return changed;
+};
+
 // src/merge/merge-project.ts
 var SANDBOX_MERGE = "sandbox";
 var UnsafeMergeError = class extends Error {
@@ -1247,35 +1334,34 @@ var defaultOptions = {
   workflowMappings: {},
   removeUnmapped: false,
   force: true,
-  /**
-   * If mode is sandbox, basically only content will be merged and all metadata/settings/options/config is ignored
-   * If mode is replace, all properties on the source will override the target (including UUIDs, name)
-   */
-  mode: SANDBOX_MERGE
+  mode: SANDBOX_MERGE,
+  onlyUpdated: false
 };
 function merge(source, target, opts) {
   const options = defaultsDeep(
     opts,
     defaultOptions
   );
-  const dupTargetMappings = getDuplicates(
-    Object.values(options.workflowMappings ?? {})
-  );
-  if (dupTargetMappings.length) {
-    throw new Error(
-      `The following target workflows have multiple source workflows merging into them: ${dupTargetMappings.join(
-        ", "
-      )}`
-    );
-  }
   const finalWorkflows = [];
   const usedTargetIds = /* @__PURE__ */ new Set();
-  const noMappings = isEmpty(options?.workflowMappings);
-  let sourceWorkflows = source.workflows.filter((w) => {
-    if (noMappings)
-      return true;
-    return !!options?.workflowMappings[w.id];
-  });
+  let sourceWorkflows = source.workflows;
+  const noMappings = isEmpty(options.workflowMappings);
+  if (options.onlyUpdated) {
+    sourceWorkflows = find_changed_workflows_default(source);
+  }
+  if (!noMappings) {
+    const dupes = getDuplicates(Object.values(options.workflowMappings ?? {}));
+    if (dupes.length) {
+      throw new Error(
+        `The following target workflows have multiple source workflows merging into them: ${dupes.join(
+          ", "
+        )}`
+      );
+    }
+    sourceWorkflows = source.workflows.filter(
+      (w) => !!options.workflowMappings[w.id]
+    );
+  }
   const potentialConflicts = {};
   for (const sourceWorkflow of sourceWorkflows) {
     const targetId = options.workflowMappings?.[sourceWorkflow.id] ?? sourceWorkflow.id;
@@ -1327,6 +1413,7 @@ Pass --force to force the merge anyway`
       ...source.options
     },
     name: source.name ?? target.name,
+    alias: source.alias ?? target.alias,
     description: source.description ?? target.description,
     credentials: source.credentials ?? target.credentials,
     collections: source.collections ?? target.collections
@@ -1337,9 +1424,12 @@ Pass --force to force the merge anyway`
 }
 
 // src/util/project-diff.ts
-function diff(a, b) {
+function diff(a, b, workflows) {
   const diffs = [];
   for (const workflowA of a.workflows) {
+    if (workflows?.length && !workflows.includes(workflowA.id)) {
+      continue;
+    }
     const workflowB = b.getWorkflow(workflowA.id);
     if (!workflowB) {
       diffs.push({ id: workflowA.id, type: "removed" });
@@ -1348,6 +1438,9 @@ function diff(a, b) {
     }
   }
   for (const workflowB of b.workflows) {
+    if (workflows?.length && !workflows.includes(workflowB.id)) {
+      continue;
+    }
     if (!a.getWorkflow(workflowB.id)) {
       diffs.push({ id: workflowB.id, type: "added" });
     }
@@ -1357,7 +1450,7 @@ function diff(a, b) {
 
 // src/Project.ts
 var maybeCreateWorkflow = (wf) => wf instanceof Workflow_default ? wf : new Workflow_default(wf);
-var Project = class {
+var Project = class _Project {
   // what schema version is this?
   // And how are we tracking this?
   // version;
@@ -1431,6 +1524,10 @@ var Project = class {
   get alias() {
     return this.cli.alias ?? "main";
   }
+  set alias(value) {
+    this.cli ??= {};
+    this.cli.alias = value;
+  }
   get uuid() {
     return this.openfn?.uuid ? `${this.openfn.uuid}` : void 0;
   }
@@ -1486,8 +1583,8 @@ var Project = class {
     return result;
   }
   // Compare this project with another and return a list of workflow changes
-  diff(project) {
-    return diff(this, project);
+  diff(project, workflows = []) {
+    return diff(this, project, workflows);
   }
   canMergeInto(target) {
     const potentialConflicts = {};
@@ -1503,6 +1600,16 @@ var Project = class {
     }
     return true;
   }
+  /**
+   * Generates the contents of the openfn.yaml file,
+   * plus its file path
+   */
+  generateConfig() {
+    return extractConfig(this);
+  }
+  clone() {
+    return new _Project(this.serialize("project"));
+  }
 };
 var Project_default = Project;
 
@@ -1623,6 +1730,12 @@ var Workspace = class {
   list() {
     return this.projects;
   }
+  get projectsPath() {
+    return path4.join(this.root, this.config.dirs.projects);
+  }
+  get workflowsPath() {
+    return path4.join(this.root, this.config.dirs.workflows);
+  }
   /** Get a project by its alias, id or UUID. Can also include a UUID */
   get(nameyThing) {
     return match_project_default(nameyThing, this.projects);
@@ -1683,12 +1796,18 @@ var initOperations = (options = {}) => {
     if (!nodes[name]) {
       const id = slugify(name);
       nodes[name] = {
-        name,
-        id,
-        openfn: {
-          uuid: uuid(id)
-        }
+        id
       };
+      if (/^(cron|webhook)$/.test(name)) {
+        nodes[name].type = name;
+      } else {
+        nodes[name].name = name;
+      }
+      if (options.openfnUuid !== false) {
+        nodes[name].openfn = {
+          uuid: uuid(id)
+        };
+      }
     }
     return nodes[name];
   };
@@ -1725,9 +1844,11 @@ var initOperations = (options = {}) => {
       const n1 = parent.buildWorkflow();
       const n2 = child.buildWorkflow();
       const e = edge.buildWorkflow();
-      e.openfn.uuid = uuid(`${n1.id}-${n2.id}`);
+      if (options.openfnUuid !== false) {
+        e.openfn.uuid = uuid(`${n1.id}-${n2.id}`);
+      }
       n1.next ??= {};
-      n1.next[n2.name] = e;
+      n1.next[n2.id ?? slugify(n2.name)] = e;
       return [n1, n2];
     },
     // node could just be a node name, or a node with props
@@ -1833,6 +1954,9 @@ function generateWorkflow(def, options = {}) {
     raw.openfn.uuid = uuid;
   }
   const wf = new Workflow_default(raw);
+  if (options.history) {
+    wf.pushHistory(wf.getVersionHash());
+  }
   return wf;
 }
 function generateProject(name, workflowDefs, options = {}) {
@@ -1858,7 +1982,9 @@ export {
   src_default as default,
   diff,
   generateProject,
+  generateHash as generateVersionHash,
   generateWorkflow,
   jsonToYaml,
+  match as versionsEqual,
   yamlToJson
 };

package/dist/workflow.ohm

@@ -29,7 +29,7 @@ Workflow {
 
   prop = (alnum | "-" | "_")+ "=" propValue
 
-  propValue = quoted_prop | bool | int | alnum+ 
+  propValue = quoted_prop | bool | int | alnum+
 
   // TODO we only parse numbers as positive ints right now
   // fine for tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/project",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Read, serialize, replicate and sync OpenFn projects",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
     "lodash-es": "^4.17.21",
     "ohm-js": "^17.2.1",
     "yaml": "^2.2.2",
-    "@openfn/lexicon": "^1.4.0",
+    "@openfn/lexicon": "^1.4.1",
     "@openfn/logger": "1.1.1"
   },
   "files": [