@openfn/project 0.4.1 → 0.5.1

package/README.md

@@ -0,0 +1,81 @@
+## openfn/project
+
+A package to track, parse and serialize OpenFn project definitions.
+
+A PROJECT is defined as a set of connected workflows with a single billing account, like a project in the app.
+
+A single Project can be Checked Out to disk at a time, meaning its source workflows and expressions will be expanded nicely onto the file system.
+
+A Workspace is a set of related Projects , including a Project and its associated Sandboxes, or a Project deployed to apps in multiple web domains
+
+### Serializing and Parsing
+
+The main idea of Projects is that a Project represents a set of OpenFn workflows defined in any format and present a standard JS-friendly interface to manipulate and reason about them.
+
+The from/to serializers are designed to support the following formats:
+
+- Projects expanded to the file system (through CLI or hand-written)
+- v1 JSON state files generated by `openfn pull`
+- v2 Project files (basically v1 state with some extra props)
+
+Serializers and parsers also support JSON and YAML formats interchangeably.
+
+### Project & Workflow Generation
+
+`project` exports utility functions to generate Projects and Workflows from a simple syntax. This is useful for testing.
+
+Really it's a Workflow generator, but you can have it wrapped in a Project if you like.
+
+Use it like this:
+
+```
+import { generateProject, generateWorkflow } from '@openfn/project'
+import type { Project, Workflow } from '@openfn/project'
+
+const proj: Project = generateProject('my-project', ['a-b b-c'])
+const wfL Workflow = generateWorkflow('a-b b-c')
+```
+
+Project generation uses a simple string language to represent a workflow structure:
+
+Define nodes in pairs seperated by a dash (no whitespace)
+
+```
+a-b # parent-child
+```
+
+For multiple children, define multiple pairs:
+
+```
+a-b
+a-c
+```
+
+You can set properties on the workflow itself - probably the id, with `@attributes`
+
+```
+@id my-cool-workflow
+```
+
+You can also set properties on a node by putting comma seperated key-value pairs in brackets
+
+```
+a(adaptor=http)
+```
+
+You can use quotes to include spaces and brackets in a property value - great for expressions:
+
+```
+a(expression="fn(s => s)")
+```
+
+You can comment inside the string with `#`, which is a basic single-line comment
+
+Reference:
+
+```
+# Comments behind hashes
+@attribute-name attribute-value
+parent(propName=propValue,x=y)-child
+a-b # can comment here to
+```

package/dist/index.d.ts

@@ -15,7 +15,7 @@ declare class Workflow {
         uuid: {};
         id: {};
     };
-    name: string;
+    name?: string;
     id: string;
     openfn: OpenfnMeta;
     constructor(workflow: l.Workflow);
@@ -31,6 +31,7 @@ declare class Workflow {
     }) | undefined;
     getUUID(id: any): string;
     toJSON(): JSON.Object;
+    getUUIDMap(): Record<string, string>;
 }
 
 type FromFsConfig = {
@@ -47,6 +48,10 @@ type FileFormats = 'yaml' | 'json';
 interface OpenfnConfig {
     name: string;
     workflowRoot: string;
+    dirs: {
+        workflows: string;
+        projects: string;
+    };
     formats: {
         openfn: FileFormats;
         project: FileFormats;
@@ -82,7 +87,9 @@ declare class Project {
     collections: any;
     static from(type: 'state', data: any, options: Partial<l.ProjectConfig>): Project;
     static from(type: 'fs', options: FromFsConfig): Project;
-    static from(type: 'path', data: any): Project;
+    static from(type: 'path', data: string, options?: {
+        config?: Partial<OpenfnConfig>;
+    }): Project;
     static diff(a: Project, b: Project): void;
     static merge(source: Project, target: Project, options: MergeProjectOptions): Project;
     constructor(data: l.Project, repoConfig?: RepoOptions);
@@ -92,6 +99,13 @@ declare class Project {
     getIdentifier(): string;
     compare(proj: Project): void;
     getUUID(workflow: string | Workflow, stepId: string, otherStep?: string): any;
+    /**
+     * Returns a map of ids:uuids for everything in the project
+     */
+    getUUIDMap(options?: {
+        workflows: boolean;
+        project: false;
+    }): {};
 }
 
 declare class Workspace {
@@ -104,7 +118,7 @@ declare class Workspace {
     get(id: string): Project | undefined;
     getProjectPath(id: string): string | undefined;
     getActiveProject(): Project | undefined;
-    getConfig(): OpenfnConfig | undefined;
+    getConfig(): Partial<OpenfnConfig>;
     get activeProjectId(): string | undefined;
     get valid(): boolean;
 }
@@ -115,13 +129,18 @@ declare function jsonToYaml(json: string | JSONObject): string;
 type GenerateWorkflowOptions = {
     name: string;
     uuidSeed: number;
+    printErrors: boolean;
+    uuidMap?: Record<string, string>;
     openfnUuid: boolean;
 };
+type GenerateProjectOptions = GenerateWorkflowOptions & {
+    uuidMap: Array<Record<string, string>>;
+};
 /**
  * Generate a Workflow from a simple text based representation
- * The def array contains strings of pairs of nodes
- * eg, ['a-b', 'b-c']
+ * eg, `a-b b-c a-c`
  */
-declare function generateWorkflow(def: string[], options?: Partial<GenerateWorkflowOptions>): Workflow;
+declare function generateWorkflow(def: string, options?: Partial<GenerateWorkflowOptions>): Workflow;
+declare function generateProject(name: string, workflowDefs: string[], options?: Partial<GenerateProjectOptions>): Project;
 
-export { Workspace, Project as default, generateWorkflow as generate, jsonToYaml, yamlToJson };
+export { Workspace, Project as default, generateProject, generateWorkflow, jsonToYaml, yamlToJson };

package/dist/index.js

@@ -4,6 +4,11 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/util/slugify.ts
+function slugify(text) {
+  return text?.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase();
+}
+
 // src/Workflow.ts
 var clone = (obj) => JSON.parse(JSON.stringify(obj));
 var Workflow = class {
@@ -26,8 +31,15 @@ var Workflow = class {
     };
     this.workflow = clone(workflow);
     const { id, name, openfn, steps, ...options } = workflow;
-    this.id = id;
+    if (!(id || name)) {
+      throw new Error("A Workflow MUST have a name or id");
+    }
+    this.id = id ?? slugify(name);
     this.name = name;
+    this.workflow.id = this.id;
+    if (name) {
+      this.workflow.name = this.name;
+    }
     this.openfn = openfn;
     this.options = options;
     this.#buildIndex();
@@ -123,6 +135,9 @@ var Workflow = class {
   toJSON() {
     return this.workflow;
   }
+  getUUIDMap() {
+    return this.index.uuid;
+  }
 };
 var Workflow_default = Workflow;
 
@@ -152,7 +167,7 @@ function to_json_default(project) {
 }
 
 // src/util/rename-keys.ts
-function renameKeys(props, keyMap) {
+function renameKeys(props = {}, keyMap) {
   return Object.fromEntries(
     Object.entries(props).map(([key, value]) => [
       keyMap[key] ? keyMap[key] : key,
@@ -178,7 +193,7 @@ function jsonToYaml(json) {
 // src/serialize/to-app-state.ts
 import { randomUUID } from "node:crypto";
 function to_app_state_default(project, options = {}) {
-  const { uuid: id, endpoint, env, ...rest } = project.openfn;
+  const { uuid: id, endpoint, env, ...rest } = project.openfn ?? {};
   const state = {
     id,
     name: project.name,
@@ -199,9 +214,11 @@ var mapWorkflow = (workflow) => {
   if (workflow instanceof Workflow_default) {
     workflow = workflow.toJSON();
   }
+  const { uuid, ...originalOpenfnProps } = workflow.openfn ?? {};
   const wfState = {
+    ...originalOpenfnProps,
+    id: workflow.openfn?.uuid ?? randomUUID(),
     name: workflow.name,
-    ...renameKeys(workflow.openfn, { uuid: "id" }),
     jobs: [],
     triggers: [],
     edges: []
@@ -262,16 +279,16 @@ import nodepath from "path";
 var stringify = (json) => JSON.stringify(json, null, 2);
 function to_fs_default(project) {
   const files = {};
-  const { path: path3, content } = extractRepoConfig(project);
-  files[path3] = content;
+  const { path: path4, content } = extractRepoConfig(project);
+  files[path4] = content;
   for (const wf of project.workflows) {
-    const { path: path4, content: content2 } = extractWorkflow(project, wf.id);
-    files[path4] = content2;
+    const { path: path5, content: content2 } = extractWorkflow(project, wf.id);
+    files[path5] = content2;
     for (const s of wf.steps) {
       const result = extractStep(project, wf.id, s.id);
       if (result) {
-        const { path: path5, content: content3 } = result;
-        files[path5] = content3;
+        const { path: path6, content: content3 } = result;
+        files[path6] = content3;
       }
     }
   }
@@ -284,7 +301,7 @@ var extractWorkflow = (project, workflowId2) => {
     throw new Error(`workflow not found: ${workflowId2}`);
   }
   const root = project.repo?.workflowRoot ?? "workflows/";
-  const path3 = nodepath.join(root, workflow.id, workflow.id);
+  const path4 = nodepath.join(root, workflow.id, workflow.id);
   const wf = {
     id: workflow.id,
     name: workflow.name,
@@ -299,7 +316,7 @@ var extractWorkflow = (project, workflowId2) => {
       return mapped;
     })
   };
-  return handleOutput(wf, path3, format);
+  return handleOutput(wf, path4, format);
 };
 var extractStep = (project, workflowId2, stepId) => {
   const workflow = project.getWorkflow(workflowId2);
@@ -312,9 +329,9 @@ var extractStep = (project, workflowId2, stepId) => {
   }
   if (step.expression) {
     const root = project.config?.workflowRoot ?? "workflows/";
-    const path3 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
+    const path4 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
     const content = step.expression;
-    return { path: path3, content };
+    return { path: path4, content };
   }
 };
 var extractRepoConfig = (project) => {
@@ -327,7 +344,7 @@ var extractRepoConfig = (project) => {
   return handleOutput(config, "openfn", format);
 };
 var handleOutput = (data, filePath, format) => {
-  const path3 = `${filePath}.${format}`;
+  const path4 = `${filePath}.${format}`;
   let content;
   if (format === "json") {
     content = stringify(data, null, 2);
@@ -336,18 +353,20 @@ var handleOutput = (data, filePath, format) => {
   } else {
     throw new Error(`Unrecognised format: ${format}`);
   }
-  return { path: path3, content };
+  return { path: path4, content };
 };
 
 // src/parse/from-app-state.ts
-function slugify(text) {
+function slugify2(text) {
   return text.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase();
 }
 var from_app_state_default = (state, config) => {
-  if (config.format === "yaml") {
-    state = yamlToJson(state);
-  } else if (typeof state === "string") {
-    state = JSON.parse(state);
+  if (typeof state === "string") {
+    if (config?.format === "yaml") {
+      state = yamlToJson(state);
+    } else {
+      state = JSON.parse(state);
+    }
   }
   const {
     id,
@@ -362,13 +381,11 @@ var from_app_state_default = (state, config) => {
   } = state;
   const proj = {
     name,
-    // TODO do we need to slug this or anything?
     description,
     collections,
     credentials,
     options
   };
-  const repoConfig = {};
   proj.openfn = {
     uuid: id,
     endpoint: config.endpoint,
@@ -380,7 +397,7 @@ var from_app_state_default = (state, config) => {
     fetched_at: config.fetchedAt
   };
   proj.workflows = state.workflows.map(mapWorkflow2);
-  return new Project(proj, repoConfig);
+  return new Project(proj, config?.repo);
 };
 var mapTriggerEdgeCondition = (edge) => {
   const e = {
@@ -401,11 +418,13 @@ var mapTriggerEdgeCondition = (edge) => {
 var mapWorkflow2 = (workflow) => {
   const { jobs, edges, triggers, name, ...remoteProps } = workflow;
   const mapped = {
-    id: slugify(workflow.name),
     name: workflow.name,
     steps: [],
     openfn: renameKeys(remoteProps, { id: "uuid" })
   };
+  if (workflow.name) {
+    mapped.id = slugify2(workflow.name);
+  }
   workflow.triggers.forEach((trigger) => {
     const { type, ...otherProps } = trigger;
     const connectedEdges = edges.filter(
@@ -420,7 +439,7 @@ var mapWorkflow2 = (workflow) => {
         if (!target) {
           throw new Error(`Failed to find ${edge.target_job_id}`);
         }
-        obj[slugify(target.name)] = mapTriggerEdgeCondition(edge);
+        obj[slugify2(target.name)] = mapTriggerEdgeCondition(edge);
         return obj;
       }, {})
     });
@@ -431,7 +450,7 @@ var mapWorkflow2 = (workflow) => {
     );
     const { body: expression, name: name2, adaptor, ...remoteProps2 } = step;
     const s = {
-      id: slugify(name2),
+      id: slugify2(name2),
       name: name2,
       expression,
       adaptor,
@@ -440,7 +459,7 @@ var mapWorkflow2 = (workflow) => {
     if (outboundEdges.length) {
       s.next = outboundEdges.reduce((next, edge) => {
         const target = jobs.find((j) => j.id === edge.target_job_id);
-        next[slugify(target.name)] = mapTriggerEdgeCondition(edge);
+        next[slugify2(target.name)] = mapTriggerEdgeCondition(edge);
         return next;
       }, {});
     }
@@ -449,6 +468,30 @@ var mapWorkflow2 = (workflow) => {
   return mapped;
 };
 
+// src/parse/from-path.ts
+import { extname } from "node:path";
+import { readFile } from "node:fs/promises";
+var from_path_default = async (path4, options = {}) => {
+  const ext = extname(path4).toLowerCase();
+  const source = await readFile(path4, "utf8");
+  const config = {
+    format: null,
+    repo: options.repo ?? options.config
+    // TMP
+  };
+  let state;
+  if (ext === ".json") {
+    config.format = "json";
+    state = JSON.parse(source);
+  } else if (ext.match(/(ya?ml)$/)) {
+    config.format = "yaml";
+    state = yamlToJson(source);
+  } else {
+    throw new Error(`Cannot load a project from a ${ext} file`);
+  }
+  return from_app_state_default(state, config);
+};
+
 // src/parse/from-fs.ts
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -496,8 +539,12 @@ var parseProject = async (options = {}) => {
     env: config.project?.env
   });
   try {
-    const format = config.formats.project ?? "yaml";
-    const statePath = path.join(root, ".projects", `${identifier}.${format}`);
+    const format = config.formats?.project ?? config.formats?.projects ?? "yaml";
+    const statePath = path.join(
+      root,
+      config.dirs?.projects ?? ".projects",
+      `${identifier}.${format}`
+    );
     const stateFile = await fs.readFile(statePath, "utf8");
     state = from_app_state_default(stateFile, { format });
   } catch (e) {
@@ -505,7 +552,8 @@ var parseProject = async (options = {}) => {
   }
   const { project: openfn, ...repo } = config;
   proj.openfn = openfn;
-  const workflowDir = config.workflowRoot ?? "workflows";
+  proj.config = repo;
+  const workflowDir = config.workflowRoot ?? config.dirs?.workflows ?? "workflows";
   const fileType = config.formats?.workflow ?? "yaml";
   const pattern = `${root}/${workflowDir}/*/*.${fileType}`;
   const candidateWfs = await glob(pattern, {
@@ -522,7 +570,6 @@ var parseProject = async (options = {}) => {
           uuid: wfState.openfn?.uuid ?? null
           // TODO do we need to transfer more stuff?
         };
-        console.log("Loading workflow at ", filePath);
         for (const step of wf.steps) {
           if (step.expression && step.expression.endsWith(".js")) {
             const dir = path.dirname(filePath);
@@ -560,7 +607,9 @@ var parseProject = async (options = {}) => {
 var getUuidForStep = (project, workflow, stepId) => {
   const wf = typeof workflow === "string" ? project.getWorkflow(workflow) : workflow;
   if (!wf) {
-    throw new Error(`Workflow "${workflow} not found in project ${project.id}`);
+    throw new Error(
+      `Workflow "${workflow}" not found in project ${project.id}`
+    );
   }
   for (const step of wf.steps) {
     if (step.id === stepId) {
@@ -945,6 +994,7 @@ function merge(source, target, options) {
 // src/Project.ts
 var maybeCreateWorkflow = (wf) => wf instanceof Workflow_default ? wf : new Workflow_default(wf);
 var setConfigDefaults = (config = {}) => ({
+  ...config,
   workflowRoot: config.workflowRoot ?? "workflows",
   formats: {
     // TODO change these maybe
@@ -971,7 +1021,7 @@ var Project = class {
   meta;
   // this contains meta about the connected openfn project
   openfn;
-  // repo configuration options
+  // workspace-wide configuration options
   // these should be shared across projects
   // and saved to an openfn.yaml file
   repo;
@@ -986,6 +1036,8 @@ var Project = class {
       return from_app_state_default(data, options);
     } else if (type === "fs") {
       return parseProject(data, options);
+    } else if (type === "path") {
+      return from_path_default(data, options);
     }
     throw new Error(`Didn't recognize type ${type}`);
   }
@@ -1047,7 +1099,21 @@ var Project = class {
     }
     return getUuidForStep(this, workflow, stepId);
   }
+  /**
+   * Returns a map of ids:uuids for everything in the project
+   */
+  getUUIDMap(options = {}) {
+    const result = {};
+    for (const wf of this.workflows) {
+      result[wf.id] = {
+        self: wf.openfn?.uuid,
+        children: wf.getUUIDMap()
+      };
+    }
+    return result;
+  }
 };
+var Project_default = Project;
 
 // src/util/path-exists.ts
 import fs2 from "fs";
@@ -1076,16 +1142,19 @@ var Workspace = class {
   projectPaths = /* @__PURE__ */ new Map();
   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);
     }
+    const projectsPath = path2.join(
+      workspacePath,
+      this.config?.dirs?.projects ?? PROJECTS_DIRECTORY
+    );
     if (this.isValid && pathExists(projectsPath, "directory")) {
       const stateFiles = fs3.readdirSync(projectsPath).filter(
-        (fileName) => PROJECT_EXTENSIONS.includes(path2.extname(fileName))
+        (fileName) => PROJECT_EXTENSIONS.includes(path2.extname(fileName)) && path2.parse(fileName).name !== "openfn"
       );
       this.projects = stateFiles.map((file) => {
         const stateFilePath = path2.join(projectsPath, file);
@@ -1093,7 +1162,7 @@ var Workspace = class {
         const project = from_app_state_default(data, { format: "yaml" });
         this.projectPaths.set(project.name, stateFilePath);
         return project;
-      });
+      }).filter((s) => s);
     }
   }
   list() {
@@ -1119,67 +1188,156 @@ var Workspace = class {
   }
 };
 
-// src/gen/workflow-generator.ts
+// src/gen/generator.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-
-// src/util/slugify.ts
-function slugify2(text) {
-  return text.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase();
-}
-
-// src/gen/workflow-generator.ts
-function gen(def, name = "workflow", uuidSeed, openfnUuid) {
-  const ids = /* @__PURE__ */ new Map();
-  const nodes = {};
-  for (const conn of def) {
-    const [from, to] = conn.split("-");
-    if (nodes[from]) {
-      if (to) {
-        if (!nodes[from].next?.[to]) {
-          nodes[from].next ??= {};
-          nodes[from].next[to] = edge(`${from}-${to}`);
+import path3 from "node:path";
+import { readFileSync } from "node:fs";
+import { grammar } from "ohm-js";
+var parser;
+var initOperations = (options = {}) => {
+  let nodes = {};
+  const uuidMap = options.uuidMap ?? {};
+  const uuid = (id) => {
+    if (id in uuidMap) {
+      return uuidMap[id];
+    }
+    return options.uuidSeed ? options.uuidSeed++ : randomUUID2();
+  };
+  const buildNode = (name) => {
+    if (!nodes[name]) {
+      const id = slugify(name);
+      nodes[name] = {
+        name,
+        id,
+        openfn: {
+          uuid: uuid(id)
         }
-      }
-    } else {
-      let props;
-      if (to) {
-        props = { next: { [to]: edge(`${from}-${to}`) } };
-      }
-      nodes[from] = node(from, props);
+      };
     }
-    if (to && !nodes[to]) {
-      nodes[to] = node(to);
+    return nodes[name];
+  };
+  const operations = {
+    Workflow(attrs, pair) {
+      pair.children.forEach((child) => child.buildWorkflow());
+      const steps = Object.values(nodes);
+      const attributes = attrs.children.map((c) => c.buildWorkflow()).reduce((obj, next) => {
+        const [key, value] = next;
+        obj[key] = value;
+        return obj;
+      }, {});
+      return { ...attributes, steps };
+    },
+    comment(_a, _b) {
+      return null;
+    },
+    attribute(_, name, _space, value) {
+      return [name.sourceString, value.sourceString];
+    },
+    Pair(parent, edge, child) {
+      const n1 = parent.buildWorkflow();
+      const n2 = child.buildWorkflow();
+      const e = edge.buildWorkflow();
+      e.openfn.uuid = uuid(`${n1.id}-${n2.id}`);
+      n1.next ??= {};
+      n1.next[n2.name] = e;
+      return [n1, n2];
+    },
+    // node could just be a node name, or a node with props
+    // different results have different requirements
+    // Not sure the best way to handle this, but this seems to work
+    node(node) {
+      if (node._node.ruleName === "node_name") {
+        return buildNode(node.sourceString);
+      }
+      return node.buildWorkflow();
+    },
+    nodeWithProps(nameNode, props) {
+      const name = nameNode.sourceString;
+      const node = buildNode(name);
+      props.buildWorkflow().forEach(([key, value]) => {
+        nodes[name][key] = value;
+      });
+      return node;
+    },
+    node_name(n) {
+      return n.sourceString;
+    },
+    props(_lbr, props, _rbr) {
+      return props.asIteration().children.map((c) => c.buildWorkflow());
+    },
+    prop(key, _op, value) {
+      return [key.sourceString, value.buildWorkflow()];
+    },
+    // Bit flaky - we need this to handle quoted props
+    _iter(...items) {
+      return items.map((i) => i.buildWorkflow()).join("");
+    },
+    alnum(a) {
+      return a.sourceString;
+    },
+    quotedProp(_left, value, _right) {
+      return value.sourceString;
+    },
+    edge(_) {
+      return {
+        openfn: {}
+      };
     }
-  }
+  };
+  return operations;
+};
+var createParser = () => {
+  const grammarPath = path3.resolve(import.meta.dirname, "workflow.ohm");
+  const contents = readFileSync(grammarPath, "utf-8");
+  const parser2 = grammar(contents);
   return {
-    name,
-    id: slugify2(name),
-    steps: Object.values(nodes),
-    ...openfnUuid ? { openfn: { uuid: randomUUID2() } } : {}
+    parse(str, options) {
+      const { printErrors = true } = options;
+      const semantics = parser2.createSemantics();
+      semantics.addOperation("buildWorkflow", initOperations(options));
+      const result = parser2.match(str);
+      if (!result.succeeded()) {
+        if (printErrors) {
+          console.error(result.shortMessage);
+          console.error(result.message);
+        }
+        throw new Error("Parsing failed!" + result.shortMessage);
+      }
+      const adaptor = semantics(result);
+      return adaptor.buildWorkflow();
+    }
   };
-  function node(id, props = {}) {
-    return {
-      id,
-      ...props,
-      openfn: { uuid: uuid(id) }
-    };
+};
+function generateWorkflow(def, options = {}) {
+  if (!parser) {
+    parser = createParser();
   }
-  function edge(id, props = {}) {
-    return {
-      ...props,
-      openfn: { uuid: uuid(id) }
-    };
+  const raw = parser.parse(def, options);
+  if (!raw.name) {
+    raw.name = "Workflow";
   }
-  function uuid(id) {
-    const muuid = !isNaN(uuidSeed) ? ++uuidSeed : randomUUID2();
-    ids.set(id, muuid);
-    return muuid;
+  if (!raw.id) {
+    raw.id = "workflow";
   }
+  if (options.openfnUuid) {
+    raw.openfn ??= {};
+    raw.openfn.uuid = randomUUID2();
+  }
+  const wf = new Workflow_default(raw);
+  return wf;
 }
-function generateWorkflow(def, options = {}) {
-  const { name, uuidSeed, openfnUuid } = options;
-  const wf = gen(def, name, uuidSeed, openfnUuid);
-  return new Workflow_default(wf);
+function generateProject(name, workflowDefs, options = {}) {
+  const workflows = workflowDefs.map(
+    (w, idx) => generateWorkflow(w, {
+      ...options,
+      uuidMap: options.uuidMap && options.uuidMap[idx]
+    })
+  );
+  return new Project_default({
+    name,
+    workflows,
+    openfn: options.openfnUuid && { uuid: randomUUID2() }
+  });
 }
 
 // src/index.ts
@@ -1187,7 +1345,8 @@ var src_default = Project;
 export {
   Workspace,
   src_default as default,
-  generateWorkflow as generate,
+  generateProject,
+  generateWorkflow,
   jsonToYaml,
   yamlToJson
 };

package/dist/workflow.ohm

@@ -0,0 +1,38 @@
+/**
+  * Ohm grammar for interpreting our Workflow syntax
+  * https://ohmjs.org/docs/intro
+  */
+Workflow {
+  Workflow = attribute* Pair*
+
+  attribute = "@" attr_name space attr_name
+
+  attr_name = (alnum | "_" | "-")+
+
+  Pair =  node edge node
+
+  comment = "#" (~lineTerminator any)*
+
+  space := " " | "\t" | lineTerminator | comment
+
+  /* lower case is important: it disables whitespace */
+  node = nodeWithProps | node_name
+
+  nodeWithProps = node_name props
+
+  /* A node name can contain letters, numbers or underscores */
+  node_name = (alnum | "_")+
+
+  props = "(" listOf<prop, ","> ")"
+
+  prop = alnum+ "=" propValue
+
+  propValue = alnum+ | quotedProp
+  
+  quotedProp = "\"" (~"\"" any)* "\""
+
+  edge = "-"
+
+  lineTerminator =  "\n" | "\r"
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/project",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Read, serialize, replicate and sync OpenFn projects",
   "type": "module",
   "exports": {
@@ -28,9 +28,11 @@
   },
   "dependencies": {
     "glob": "^11.0.2",
+    "lodash": "^4.17.21",
     "lodash-es": "^4.17.21",
+    "ohm-js": "^17.2.1",
     "yaml": "^2.2.2",
-    "@openfn/lexicon": "^1.2.3",
+    "@openfn/lexicon": "^1.2.4",
     "@openfn/logger": "1.0.6"
   },
   "files": [
@@ -41,8 +43,7 @@
     "test": "pnpm ava",
     "test:watch": "pnpm ava -w",
     "test:types": "pnpm tsc --noEmit --project tsconfig.json",
-    "build": "tsup --config ../../tsup.config.js src/index.ts",
-    "build:watch": "pnpm build --watch",
+    "build": "tsup --config ../../tsup.config.js src/index.ts && cp src/gen/workflow.ohm dist/workflow.ohm",
     "pack": "pnpm pack --pack-destination ../../dist"
   }
 }