@openfn/project 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,66 @@
 import * as l from '@openfn/lexicon';
 
+type OpenfnMeta = {
+    uuid?: string;
+};
+type WithMeta<T> = T & {
+    openfn?: OpenfnMeta;
+};
+declare class Workflow {
+    #private;
+    workflow: l.Workflow;
+    index: {
+        steps: {};
+        edges: {};
+        uuid: {};
+        id: {};
+    };
+    name: string;
+    id: string;
+    openfn: OpenfnMeta;
+    steps: WithMeta<l.Job | l.Trigger>[];
+    constructor(workflow: l.Workflow);
+    get steps(): (l.Job | l.Trigger)[];
+    set(id: string, props: Parital<l.Job, l.Edge>): this;
+    get(id: any): WithMeta<l.Step | l.Trigger | l.Edge>;
+    meta(id: any): OpenfnMeta;
+    getEdge(from: any, to: any): WithMeta<l.ConditionalStepEdge>;
+    getAllEdges(): Record<string, string[]>;
+    getStep(id: string): Workflow["steps"][number];
+    getRoot(): (l.Trigger & {
+        openfn?: OpenfnMeta;
+    }) | undefined;
+    getUUID(id: any): string;
+    toJSON(): JSON.Object;
+}
+
+type FromFsConfig = {
+    root: string;
+};
+
+type MergeProjectOptions = Partial<{
+    workflowMappings: Record<string, string>;
+    removeUnmapped: boolean;
+    force: boolean;
+}>;
+
 type FileFormats = 'yaml' | 'json';
+interface OpenfnConfig {
+    name: string;
+    workflowRoot: string;
+    formats: {
+        openfn: FileFormats;
+        project: FileFormats;
+        workflow: FileFormats;
+    };
+    project: {
+        projectId: string;
+        endpoint: string;
+        env: string;
+        inserted_at: string;
+        updated_at: string;
+    };
+}
 type RepoOptions = {
     /**default workflow root when serializing to fs (relative to openfn.yaml) */
     workflowRoot?: string;
@@ -15,30 +75,40 @@ declare class Project {
     name?: string;
     description?: string;
     history: string[];
-    workflows: l.Workflow[];
+    workflows: Workflow[];
     options: any;
     meta: any;
     openfn?: l.ProjectConfig;
     repo?: Required<RepoOptions>;
+    collections: any;
     static from(type: 'state', data: any, options: Partial<l.ProjectConfig>): Project;
-    static from(type: 'fs', options: {
-        root: string;
-    }): Project;
+    static from(type: 'fs', options: FromFsConfig): Project;
     static from(type: 'path', data: any): Project;
     static diff(a: Project, b: Project): void;
+    static merge(source: Project, target: Project, options: MergeProjectOptions): Project;
     constructor(data: l.Project, repoConfig?: RepoOptions);
     serialize(type?: 'json' | 'yaml' | 'fs' | 'state', options?: any): any;
     getVersionHash(): void;
-    merge(project: Project, options: any): void;
-    getWorkflow(id: string): l.Workflow | undefined;
+    getWorkflow(id: string): Workflow | undefined;
     getIdentifier(): string;
     compare(proj: Project): void;
     getUUID(workflow: string | Workflow, stepId: string, otherStep?: string): any;
 }
-declare class Workflow {
+
+declare class Workspace {
+    private config?;
+    private projects;
+    private isValid;
+    constructor(workspacePath: string);
+    list(): Project[];
+    get(id: string): Project | undefined;
+    getActiveProject(): Project | undefined;
+    getConfig(): OpenfnConfig | undefined;
+    get activeProjectId(): string | undefined;
+    get valid(): boolean;
 }
 
 declare function yamlToJson(y: string): any;
 declare function jsonToYaml(json: string | JSONObject): string;
 
-export { Project as default, jsonToYaml, yamlToJson };
+export { Workspace, Project as default, jsonToYaml, yamlToJson };

package/dist/index.js

@@ -4,6 +4,129 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/Workflow.ts
+var clone = (obj) => JSON.parse(JSON.stringify(obj));
+var Workflow = class {
+  workflow;
+  // this is the raw workflow JSON representation
+  index;
+  name;
+  id;
+  openfn;
+  steps;
+  constructor(workflow) {
+    this.index = {
+      steps: {},
+      // steps by id
+      edges: {},
+      // edges by from-id id
+      uuid: {},
+      // id to uuid
+      id: {}
+      // uuid to ids
+    };
+    this.workflow = clone(workflow);
+    const { id, name, openfn, steps, ...options } = workflow;
+    this.id = id;
+    this.name = name;
+    this.openfn = openfn;
+    this.options = options;
+    this.#buildIndex();
+  }
+  get steps() {
+    return this.workflow.steps;
+  }
+  #buildIndex() {
+    for (const s of this.workflow.steps) {
+      this.index.steps[s.id] = s;
+      this.index.uuid[s.id] = s.openfn?.uuid;
+      if (s.openfn?.uuid) {
+        this.index.id[s.openfn.uuid] = s.id;
+      }
+      const edges = s.next ?? {};
+      for (const next in edges) {
+        const edgeId = `${s.id}-${next}`;
+        const edge = edges[next];
+        this.index.edges[edgeId] = edge;
+        this.index.uuid[edgeId] = edge.openfn?.uuid;
+        if (edge.openfn?.uuid) {
+          this.index.id[edge.openfn.uuid] = edgeId;
+        }
+      }
+    }
+  }
+  // Set properties on any step or edge by id
+  set(id, props) {
+    const item = this.index.edges[id] || this.index.steps[id];
+    if (!item) {
+      throw new Error(`step/edge with id "${id}" does not exist in workflow`);
+    }
+    Object.assign(item, props);
+    return this;
+  }
+  // Get properties on any step or edge by id
+  get(id) {
+    const item = this.index.edges[id] || this.index.steps[id];
+    if (!item) {
+      throw new Error(`step/edge with id "${id}" does not exist in workflow`);
+    }
+    return item;
+  }
+  // TODO needs unit tests and maybe setter
+  meta(id) {
+    const item = this.index.edges[id] || this.index.steps[id];
+    if (!item) {
+      throw new Error(`step/edge with id "${id}" does not exist in workflow`);
+    }
+    return item.openfn ?? {};
+  }
+  // Get an edge based on its source and target
+  getEdge(from, to) {
+    const edgeId = [from, to].join("-");
+    const edge = this.index.edges[edgeId];
+    if (!edge) {
+      throw new Error(`edge with id "${edgeId}" does not exist in workflow`);
+    }
+    return edge;
+  }
+  getAllEdges() {
+    const edges = {};
+    for (const step of this.steps) {
+      const next = typeof step.next === "string" ? { [step.next]: true } : step.next || {};
+      for (const toNode of Object.keys(next)) {
+        if (!Array.isArray(edges[step.id]))
+          edges[step.id] = [toNode];
+        else
+          edges[step.id].push(toNode);
+      }
+    }
+    return edges;
+  }
+  getStep(id) {
+    return this.index.steps[id];
+  }
+  getRoot() {
+    const edges = this.getAllEdges();
+    const all_children = [];
+    const all_parents = [];
+    for (const [parent, children] of Object.entries(edges)) {
+      all_children.push(...children);
+      all_parents.push(parent);
+    }
+    const root = all_parents.find((parent) => !all_children.includes(parent));
+    if (!root)
+      return;
+    return this.index.steps[root];
+  }
+  getUUID(id) {
+    return this.index.uuid[id];
+  }
+  toJSON() {
+    return this.workflow;
+  }
+};
+var Workflow_default = Workflow;
+
 // src/serialize/index.ts
 var serialize_exports = {};
 __export(serialize_exports, {
@@ -29,6 +152,16 @@ function to_json_default(project) {
   };
 }
 
+// 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) {
@@ -46,7 +179,7 @@ function jsonToYaml(json) {
 // src/serialize/to-app-state.ts
 import { randomUUID } from "node:crypto";
 function to_app_state_default(project, options = {}) {
-  const { projectId: id, endpoint, env, ...rest } = project.openfn;
+  const { uuid: id, endpoint, env, ...rest } = project.openfn;
   const state = {
     id,
     name: project.name,
@@ -64,19 +197,22 @@ function to_app_state_default(project, options = {}) {
   return state;
 }
 var mapWorkflow = (workflow) => {
+  if (workflow instanceof Workflow_default) {
+    workflow = workflow.toJSON();
+  }
   const wfState = {
     name: workflow.name,
-    ...workflow.openfn,
+    ...renameKeys(workflow.openfn, { uuid: "id" }),
     jobs: [],
     triggers: [],
     edges: []
   };
   const lookup = workflow.steps.reduce((obj, next) => {
-    if (!next.openfn?.id) {
+    if (!next.openfn?.uuid) {
       next.openfn ??= {};
-      next.openfn.id = randomUUID();
+      next.openfn.uuid = randomUUID();
     }
-    obj[next.id] = next.openfn.id;
+    obj[next.id] = next.openfn.uuid;
     return obj;
   }, {});
   workflow.steps.forEach((s) => {
@@ -86,7 +222,7 @@ var mapWorkflow = (workflow) => {
       isTrigger = true;
       node = {
         type: s.type,
-        ...s.openfn
+        ...renameKeys(s.openfn, { uuid: "id" })
       };
       wfState.triggers.push(node);
     } else {
@@ -94,14 +230,14 @@ var mapWorkflow = (workflow) => {
         name: s.name,
         body: s.expression,
         adaptor: s.adaptor,
-        ...s.openfn
+        ...renameKeys(s.openfn, { uuid: "id" })
       };
       wfState.jobs.push(node);
     }
     Object.keys(s.next ?? {}).forEach((next) => {
       const rules = s.next[next];
       const e = {
-        id: rules.openfn?.id ?? randomUUID(),
+        id: rules.openfn?.uuid ?? randomUUID(),
         target_job_id: lookup[next],
         enabled: !rules.disabled
       };
@@ -127,16 +263,16 @@ import nodepath from "path";
 var stringify = (json) => JSON.stringify(json, null, 2);
 function to_fs_default(project) {
   const files = {};
-  const { path: path2, content } = extractRepoConfig(project);
-  files[path2] = content;
+  const { path: path3, content } = extractRepoConfig(project);
+  files[path3] = content;
   for (const wf of project.workflows) {
-    const { path: path3, content: content2 } = extractWorkflow(project, wf.id);
-    files[path3] = content2;
+    const { path: path4, content: content2 } = extractWorkflow(project, wf.id);
+    files[path4] = content2;
     for (const s of wf.steps) {
       const result = extractStep(project, wf.id, s.id);
       if (result) {
-        const { path: path4, content: content3 } = result;
-        files[path4] = content3;
+        const { path: path5, content: content3 } = result;
+        files[path5] = content3;
       }
     }
   }
@@ -149,10 +285,12 @@ var extractWorkflow = (project, workflowId2) => {
     throw new Error(`workflow not found: ${workflowId2}`);
   }
   const root = project.repo?.workflowRoot ?? "workflows/";
-  const path2 = nodepath.join(root, workflow.id, workflow.id);
+  const path3 = nodepath.join(root, workflow.id, workflow.id);
   const wf = {
     id: workflow.id,
     name: workflow.name,
+    // Note: if no options are defined, options will serialize to an empty object
+    // Not crazy about this - maybe we should do something better? Or do we like the consistency?
     options: workflow.options,
     steps: workflow.steps.map((step) => {
       const { openfn, expression, ...mapped } = step;
@@ -162,7 +300,7 @@ var extractWorkflow = (project, workflowId2) => {
       return mapped;
     })
   };
-  return handleOutput(wf, path2, format);
+  return handleOutput(wf, path3, format);
 };
 var extractStep = (project, workflowId2, stepId) => {
   const workflow = project.getWorkflow(workflowId2);
@@ -175,9 +313,9 @@ var extractStep = (project, workflowId2, stepId) => {
   }
   if (step.expression) {
     const root = project.config?.workflowRoot ?? "workflows/";
-    const path2 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
+    const path3 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
     const content = step.expression;
-    return { path: path2, content };
+    return { path: path3, content };
   }
 };
 var extractRepoConfig = (project) => {
@@ -190,7 +328,7 @@ var extractRepoConfig = (project) => {
   return handleOutput(config, "openfn", format);
 };
 var handleOutput = (data, filePath, format) => {
-  const path2 = `${filePath}.${format}`;
+  const path3 = `${filePath}.${format}`;
   let content;
   if (format === "json") {
     content = stringify(data, null, 2);
@@ -199,7 +337,7 @@ var handleOutput = (data, filePath, format) => {
   } else {
     throw new Error(`Unrecognised format: ${format}`);
   }
-  return { path: path2, content };
+  return { path: path3, content };
 };
 
 // src/parse/from-app-state.ts
@@ -233,7 +371,7 @@ var from_app_state_default = (state, config) => {
   };
   const repoConfig = {};
   proj.openfn = {
-    projectId: id,
+    uuid: id,
     endpoint: config.endpoint,
     env: config.env,
     inserted_at,
@@ -257,7 +395,7 @@ var mapTriggerEdgeCondition = (edge) => {
     e.condition = edge.condition_expression;
   }
   e.openfn = {
-    id: edge.id
+    uuid: edge.id
   };
   return e;
 };
@@ -267,7 +405,7 @@ var mapWorkflow2 = (workflow) => {
     id: slugify(workflow.name),
     name: workflow.name,
     steps: [],
-    openfn: remoteProps
+    openfn: renameKeys(remoteProps, { id: "uuid" })
   };
   workflow.triggers.forEach((trigger) => {
     const { type, ...otherProps } = trigger;
@@ -277,7 +415,7 @@ var mapWorkflow2 = (workflow) => {
     mapped.steps.push({
       id: "trigger",
       type,
-      openfn: otherProps,
+      openfn: renameKeys(otherProps, { id: "uuid" }),
       next: connectedEdges.reduce((obj, edge) => {
         const target = jobs.find((j) => j.id === edge.target_job_id);
         if (!target) {
@@ -298,7 +436,7 @@ var mapWorkflow2 = (workflow) => {
       name: name2,
       expression,
       adaptor,
-      openfn: remoteProps2
+      openfn: renameKeys(remoteProps2, { id: "uuid" })
     };
     if (outboundEdges.length) {
       s.next = outboundEdges.reduce((next, edge) => {
@@ -382,7 +520,7 @@ var parseProject = async (options = {}) => {
       if (wf.id && Array.isArray(wf.steps)) {
         const wfState = (state && state.getWorkflow(wf.id)) ?? {};
         wf.openfn = {
-          id: wfState.openfn?.id ?? null
+          uuid: wfState.openfn?.uuid ?? null
           // TODO do we need to transfer more stuff?
         };
         console.log("Loading workflow at ", filePath);
@@ -398,14 +536,14 @@ var parseProject = async (options = {}) => {
             }
           }
           const uuid = state?.getUUID(wf.id, step.id) ?? null;
-          step.openfn = { id: uuid };
+          step.openfn = { uuid };
           for (const target in step.next || {}) {
             if (typeof step.next[target] === "boolean") {
               const bool = step.next[target];
               step.next[target] = { condition: bool };
             }
             const uuid2 = state?.getUUID(wf.id, step.id, target) ?? null;
-            step.next[target].openfn = { id: uuid2 };
+            step.next[target].openfn = { uuid: uuid2 };
           }
         }
         workflows.push(wf);
@@ -427,7 +565,7 @@ var getUuidForStep = (project, workflow, stepId) => {
   }
   for (const step of wf.steps) {
     if (step.id === stepId) {
-      return step.openfn?.id ?? null;
+      return step.openfn?.uuid ?? null;
     }
   }
   return null;
@@ -443,7 +581,7 @@ var getUuidForEdge = (project, workflow, from, to) => {
     if (step.id === from) {
       for (const edge in step.next) {
         if (edge === to) {
-          return step.next[edge].openfn?.id ?? null;
+          return step.next[edge].openfn?.uuid ?? null;
         }
       }
       break;
@@ -452,6 +590,359 @@ var getUuidForEdge = (project, workflow, from, to) => {
   return null;
 };
 
+// src/merge/merge-project.ts
+import { defaultsDeep, isEmpty } from "lodash-es";
+
+// src/util/base-merge.ts
+import { pick, assign } from "lodash-es";
+function baseMerge(target, source, sourceKeys, assigns = {}) {
+  const pickedSource = sourceKeys ? pick(source, sourceKeys) : source;
+  return assign(target, { ...pickedSource, ...assigns });
+}
+
+// src/merge/merge-node.ts
+function mergeWorkflows(source, target, mappings) {
+  const targetNodes = {};
+  for (const tstep2 of target.steps)
+    targetNodes[tstep2.openfn.uuid || tstep2.id] = tstep2;
+  const steps = [];
+  for (const sstep of source.steps) {
+    let newNode = sstep;
+    if (typeof mappings.nodes[sstep.id] === "string") {
+      const preservedId = mappings.nodes[sstep.id];
+      const preservedEdgeIds = {};
+      for (const toNode of Object.keys(
+        typeof sstep.next === "string" ? { [tstep.next]: true } : sstep.next || {}
+      )) {
+        const key = sstep.id + "-" + toNode;
+        if (typeof mappings.edges[key] === "string") {
+          const preservedEdgeId = mappings.edges[key];
+          const toEdge = sstep.next?.[toNode] || {};
+          preservedEdgeIds[toNode] = sstep.next[toNode] = {
+            ...toEdge,
+            openfn: { ...toEdge?.openfn || {}, uuid: preservedEdgeId }
+          };
+        }
+      }
+      newNode = baseMerge(targetNodes[preservedId], sstep, [
+        "id",
+        "name",
+        "adaptor",
+        "expression",
+        "next",
+        "previous"
+      ]);
+    } else {
+    }
+    steps.push(newNode);
+  }
+  const newSource = { ...source, steps };
+  return {
+    ...target,
+    ...newSource,
+    openfn: { ...target.openfn }
+    // preserving the target uuid. we might need a proper helper function for this.
+  };
+}
+
+// src/merge/map-uuids.ts
+var map_uuids_default = (source, target) => {
+  const targetEdges = target.getAllEdges();
+  const sourceEdges = source.getAllEdges();
+  const initialMapping = mapStepsById(source.steps, target.steps);
+  let nodeMapping = initialMapping.mapping;
+  let unmappedSource = initialMapping.pool.source;
+  let unmappedTarget = initialMapping.pool.target;
+  let idMap = initialMapping.idMap;
+  mapRootNodes(source, target, idMap, nodeMapping);
+  const getMappedId = (id) => idMap.get(id) || id;
+  let prevUnmapped = -1;
+  let remainingUnmapped = findRemainingUnmappedNodes(unmappedSource, idMap);
+  let lastIteration = false;
+  while (prevUnmapped !== remainingUnmapped.length || !lastIteration) {
+    lastIteration = prevUnmapped === remainingUnmapped.length;
+    for (const sourceStep of remainingUnmapped) {
+      const candidates = getUnmappedCandidates(unmappedTarget, idMap);
+      const mappingResult = findBestMatch(
+        sourceStep,
+        candidates,
+        sourceEdges,
+        targetEdges,
+        getMappedId,
+        lastIteration
+        // isLastIteration
+      );
+      if (mappingResult) {
+        nodeMapping[sourceStep.id] = getStepUuid(mappingResult);
+        idMap.set(sourceStep.id, mappingResult.id);
+      }
+    }
+    prevUnmapped = remainingUnmapped.length;
+    remainingUnmapped = findRemainingUnmappedNodes(unmappedSource, idMap);
+  }
+  const edgeMapping = mapEdges(
+    sourceEdges,
+    targetEdges,
+    idMap,
+    target.getUUID.bind(target)
+  );
+  return {
+    nodes: nodeMapping,
+    edges: edgeMapping
+  };
+};
+function mapRootNodes(source, target, idMap, nodeMapping) {
+  const sourceRoot = source.getRoot();
+  const targetRoot = target.getRoot();
+  if (sourceRoot && targetRoot) {
+    idMap.set(sourceRoot.id, targetRoot.id);
+    nodeMapping[sourceRoot.id] = getStepUuid(targetRoot);
+  }
+}
+function findRemainingUnmappedNodes(unmappedSource, idMap) {
+  return unmappedSource.filter((step) => step.id && !idMap.has(step.id));
+}
+function getUnmappedCandidates(unmappedTarget, idMap) {
+  const mappedIds = new Set(idMap.values());
+  return unmappedTarget.filter((step) => !mappedIds.has(step.id));
+}
+function findBestMatch(sourceStep, candidates, sourceEdges, targetEdges, getMappedId, isLastIteration) {
+  if (candidates.length === 0)
+    return null;
+  let bestCandidates = candidates;
+  let topResult = null;
+  let didStructuralFilter = false;
+  const parentResult = mapStepByParent(
+    sourceStep,
+    bestCandidates,
+    sourceEdges,
+    targetEdges,
+    getMappedId
+  );
+  if (parentResult.candidates.length > 0) {
+    bestCandidates = parentResult.candidates;
+    topResult = bestCandidates[0];
+    didStructuralFilter ||= parentResult.filtered;
+  }
+  if (bestCandidates.length === 1) {
+    return bestCandidates[0];
+  }
+  const childrenResult = mapStepByChildren(
+    sourceStep,
+    bestCandidates,
+    sourceEdges,
+    targetEdges,
+    getMappedId
+  );
+  if (childrenResult.candidates.length > 0) {
+    bestCandidates = childrenResult.candidates;
+    topResult = bestCandidates[0];
+    didStructuralFilter ||= childrenResult.filtered;
+  }
+  if (bestCandidates.length === 1) {
+    return bestCandidates[0];
+  }
+  const expressionCandidates = mapStepByExpression(sourceStep, bestCandidates);
+  if (expressionCandidates.length > 0) {
+    bestCandidates = expressionCandidates;
+  }
+  if (bestCandidates.length === 1) {
+    return bestCandidates[0];
+  }
+  if (isLastIteration && didStructuralFilter && topResult) {
+    return topResult;
+  }
+  return null;
+}
+function mapEdges(sourceEdges, targetEdges, idMap, getTargetUUID) {
+  const edgeMapping = {};
+  for (const [parentId, children] of Object.entries(sourceEdges)) {
+    for (const childId of children) {
+      const sourceEdgeKey = `${parentId}-${childId}`;
+      const mappedParentId = idMap.get(parentId) || parentId;
+      const mappedChildId = idMap.get(childId) || childId;
+      const targetEdgeId = getTargetUUID(`${mappedParentId}-${mappedChildId}`);
+      if (targetEdgeId) {
+        edgeMapping[sourceEdgeKey] = targetEdgeId;
+      }
+    }
+  }
+  return edgeMapping;
+}
+function getStepUuid(step) {
+  return step?.openfn?.uuid || step.id;
+}
+function mapStepsById(source, target) {
+  const targetIndex = {};
+  const mapping = {};
+  const idMap = /* @__PURE__ */ new Map();
+  for (const targetStep of target) {
+    targetIndex[targetStep.id] = targetStep;
+  }
+  const unmappedSourceIndices = [];
+  const unmappedTarget = [...target];
+  for (let i = 0; i < source.length; i++) {
+    const sourceStep = source[i];
+    const matchingTarget = targetIndex[sourceStep.id];
+    if (matchingTarget) {
+      mapping[sourceStep.id] = getStepUuid(matchingTarget);
+      idMap.set(sourceStep.id, matchingTarget.id);
+      const targetIndex2 = unmappedTarget.findIndex(
+        (t) => t.id === matchingTarget.id
+      );
+      if (targetIndex2 !== -1) {
+        unmappedTarget.splice(targetIndex2, 1);
+      }
+    } else {
+      unmappedSourceIndices.push(i);
+    }
+  }
+  return {
+    mapping,
+    idMap,
+    pool: {
+      source: source.filter((_, i) => unmappedSourceIndices.includes(i)),
+      target: unmappedTarget
+    }
+  };
+}
+function getParent(id, edges) {
+  return Object.entries(edges).filter(([, children]) => children.includes(id)).map(([parentId]) => parentId);
+}
+function findByExpression(expression, steps) {
+  return steps.filter(
+    (step) => step.expression && step.expression.trim() && step.expression === expression
+  );
+}
+function findByParent(parentIds, edges, steps) {
+  const matches = [];
+  for (const parentId of parentIds) {
+    const children = edges[parentId];
+    if (!children || children.length === 0)
+      continue;
+    const matchingSteps = steps.filter((step) => children.includes(step.id));
+    matches.push(...matchingSteps);
+  }
+  return matches;
+}
+function findByChildren(childIds, edges, steps) {
+  const childMatchCount = {};
+  for (const [parentId, children] of Object.entries(edges)) {
+    const matchCount = children.filter(
+      (childId) => childIds.includes(childId)
+    ).length;
+    if (matchCount > 0) {
+      childMatchCount[parentId] = matchCount;
+    }
+  }
+  const sortedParentIds = Object.entries(childMatchCount).sort(([, count1], [, count2]) => count2 - count1).map(([parentId]) => parentId);
+  const stepIndex = steps.reduce((index, step) => {
+    index[step.id] = step;
+    return index;
+  }, {});
+  return sortedParentIds.filter((parentId) => stepIndex[parentId]).map((parentId) => stepIndex[parentId]);
+}
+function mapStepByParent(sourceStep, candidates, sourceEdges, targetEdges, getMappedId) {
+  const sourceParents = getParent(sourceStep.id, sourceEdges);
+  if (sourceParents.length === 0) {
+    return { filtered: false, candidates };
+  }
+  const mappedParentIds = sourceParents.map(getMappedId);
+  const matchingCandidates = findByParent(
+    mappedParentIds,
+    targetEdges,
+    candidates
+  );
+  return {
+    filtered: true,
+    candidates: matchingCandidates
+  };
+}
+function mapStepByChildren(sourceStep, candidates, sourceEdges, targetEdges, getMappedId) {
+  const sourceChildren = sourceEdges[sourceStep.id];
+  if (!sourceChildren) {
+    return { filtered: false, candidates };
+  }
+  const mappedChildIds = sourceChildren.map(getMappedId);
+  const matchingCandidates = findByChildren(
+    mappedChildIds,
+    targetEdges,
+    candidates
+  );
+  return {
+    filtered: true,
+    candidates: matchingCandidates
+  };
+}
+function mapStepByExpression(sourceStep, candidates) {
+  const expression = sourceStep.expression;
+  return findByExpression(expression, candidates);
+}
+
+// src/util/get-duplicates.ts
+function getDuplicates(arr) {
+  const hmap = {};
+  const duplicates = /* @__PURE__ */ new Set();
+  for (let i = 0; i < arr.length; i++) {
+    const item = arr[i];
+    if (hmap[item])
+      duplicates.add(item);
+    else
+      hmap[item] = true;
+  }
+  return Array.from(duplicates);
+}
+
+// src/merge/merge-project.ts
+function merge(source, target, options) {
+  const defaultOptions = {
+    workflowMappings: {},
+    removeUnmapped: false
+  };
+  options = defaultsDeep(options, 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];
+  });
+  for (const sourceWorkflow of sourceWorkflows) {
+    const targetId = options.workflowMappings?.[sourceWorkflow.id] ?? sourceWorkflow.id;
+    const targetWorkflow = target.getWorkflow(targetId);
+    if (targetWorkflow) {
+      usedTargetIds.add(targetWorkflow.id);
+      const mappings = map_uuids_default(sourceWorkflow, targetWorkflow);
+      finalWorkflows.push(
+        mergeWorkflows(sourceWorkflow, targetWorkflow, mappings)
+      );
+    } else {
+      finalWorkflows.push(sourceWorkflow);
+    }
+  }
+  if (!options?.removeUnmapped) {
+    for (const targetWorkflow of target.workflows) {
+      if (!usedTargetIds.has(targetWorkflow.id)) {
+        finalWorkflows.push(targetWorkflow);
+      }
+    }
+  }
+  return new Project(
+    baseMerge(target, source, ["collections"], { workflows: finalWorkflows })
+  );
+}
+
 // src/Project.ts
 var setConfigDefaults = (config = {}) => ({
   workflowRoot: config.workflowRoot ?? "workflows",
@@ -484,11 +975,16 @@ var Project = class {
   // these should be shared across projects
   // and saved to an openfn.yaml file
   repo;
+  // load a project from a state file (project.json)
+  // or from a path (the file system)
+  // TODO presumably we can detect a state file? Not a big deal?
+  // collections for the project
+  // TODO to be well typed
+  collections;
   static from(type, data, options) {
     if (type === "state") {
       return from_app_state_default(data, options);
-    }
-    if (type === "fs") {
+    } else if (type === "fs") {
       return parseProject(data, options);
     }
     throw new Error(`Didn't recognize type ${type}`);
@@ -496,18 +992,23 @@ var Project = class {
   // Diff two projects
   static diff(a, b) {
   }
+  // Merge a source project (staging) into the target project (main)
+  // Returns a new Project
+  // TODO: throw if histories have diverged
+  static merge(source, target, options) {
+    return merge(source, target, options);
+  }
   // env is excluded because it's not really part of the project
   // uh maybe
   // maybe this second arg is config - like env, branch rules, serialisation rules
   // stuff that's external to the actual project and managed by the repo
   constructor(data, repoConfig = {}) {
     this.repo = setConfigDefaults(repoConfig);
-    this.id = data.id;
     this.name = data.name;
     this.description = data.description;
     this.openfn = data.openfn;
     this.options = data.options;
-    this.workflows = data.workflows;
+    this.workflows = data.workflows?.map((w) => new Workflow_default(w)) ?? [];
     this.collections = data.collections;
     this.credentials = data.credentials;
     this.meta = data.meta;
@@ -523,11 +1024,6 @@ var Project = class {
   // this builds a version string for the current state
   getVersionHash() {
   }
-  // take a second project and merge its data into this one
-  // Throws if there's a conflict, unless force is true
-  // It's basically an overwrite
-  merge(project, options) {
-  }
   // what else might we need?
   // get workflow by name or id
   // this is fuzzy, but is that wrong?
@@ -553,9 +1049,73 @@ var Project = class {
   }
 };
 
+// src/util/path-exists.ts
+import fs2 from "fs";
+function pathExists(fpath, type) {
+  try {
+    const stat = fs2.statSync(fpath);
+    if (type === "file" && stat.isFile())
+      return true;
+    else if (type === "directory" && stat.isDirectory())
+      return true;
+    return false;
+  } catch (e) {
+    return false;
+  }
+}
+
+// src/Workspace.ts
+import path2 from "path";
+import fs3 from "fs";
+var PROJECTS_DIRECTORY = ".projects";
+var OPENFN_YAML_FILE = "openfn.yaml";
+var PROJECT_EXTENSIONS = [".yaml", ".yml"];
+var Workspace = class {
+  config;
+  projects = [];
+  isValid = false;
+  constructor(workspacePath) {
+    const projectsPath = path2.join(workspacePath, PROJECTS_DIRECTORY);
+    const openfnYamlPath = path2.join(workspacePath, OPENFN_YAML_FILE);
+    if (pathExists(openfnYamlPath, "file")) {
+      this.isValid = true;
+      const data = fs3.readFileSync(openfnYamlPath, "utf-8");
+      this.config = yamlToJson(data);
+    }
+    if (this.isValid && pathExists(projectsPath, "directory")) {
+      const stateFiles = fs3.readdirSync(projectsPath).filter(
+        (fileName) => PROJECT_EXTENSIONS.includes(path2.extname(fileName))
+      );
+      this.projects = stateFiles.map((file) => {
+        const data = fs3.readFileSync(path2.join(projectsPath, file), "utf-8");
+        return from_app_state_default(data, { format: "yaml" });
+      });
+    }
+  }
+  list() {
+    return this.projects;
+  }
+  get(id) {
+    return this.projects.find((p) => p.name === id);
+  }
+  getActiveProject() {
+    return this.projects.find((p) => p.name === this.config?.name);
+  }
+  getConfig() {
+    return this.config;
+  }
+  get activeProjectId() {
+    return this.config?.name;
+  }
+  get valid() {
+    return this.isValid;
+  }
+};
+
 // src/index.ts
 var src_default = Project;
 export {
+  Workspace,
   src_default as default,
   jsonToYaml,
   yamlToJson

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/project",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Read, serialize, replicate and sync OpenFn projects",
   "type": "module",
   "exports": {
@@ -17,6 +17,7 @@
   "author": "Open Function Group <admin@openfn.org>",
   "license": "ISC",
   "devDependencies": {
+    "@types/lodash": "^4.17.20",
     "@types/mock-fs": "~4.13.4",
     "ava": "5.3.1",
     "mock-fs": "^5.5.0",
@@ -26,8 +27,9 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
-    "glob": "^11.0.3",
-    "yaml": "^2.8.1",
+    "glob": "^11.0.2",
+    "lodash-es": "^4.17.21",
+    "yaml": "^2.2.2",
     "@openfn/lexicon": "^1.2.3",
     "@openfn/logger": "1.0.6"
   },