@openfn/project 0.7.0 → 0.7.2

package/dist/index.d.ts

@@ -1,133 +1,114 @@
-import * as l$1 from '@openfn/lexicon';
+import * as l from '@openfn/lexicon';
+import l__default, { WorkspaceConfig, UUID } from '@openfn/lexicon';
+import { Provisioner } from '@openfn/lexicon/lightning';
 
-type OpenfnMeta = {
-    uuid?: string;
-};
 type WithMeta<T> = T & {
-    openfn?: OpenfnMeta;
+    openfn?: l.NodeMeta;
 };
 declare class Workflow {
-    #private;
-    workflow: l$1.Workflow;
-    index: {
-        steps: {};
-        edges: {};
-        uuid: {};
-        id: {};
-    };
+    workflow: l.Workflow;
+    index: any;
     name?: string;
     id: string;
-    openfn: OpenfnMeta;
-    constructor(workflow: l$1.Workflow);
-    get steps(): WithMeta<l$1.Job | l$1.Trigger>[];
-    set(id: string, props: Parital<l$1.Job, l$1.Edge>): this;
-    get(id: any): WithMeta<l$1.Step | l$1.Trigger | l$1.Edge>;
-    meta(id: any): OpenfnMeta;
-    getEdge(from: any, to: any): WithMeta<l$1.ConditionalStepEdge>;
+    openfn?: l.WorkflowMeta;
+    options: any;
+    constructor(workflow: l.Workflow);
+    get steps(): WithMeta<l.Job & l.Trigger>[];
+    _buildIndex(): void;
+    set(id: string, props: Partial<l.Job | l.StepEdge>): this;
+    get(id: string): WithMeta<l.Step | l.Trigger | l.StepEdge>;
+    meta(id: string): l.WorkflowMeta;
+    getEdge(from: string, to: string): WithMeta<l.ConditionalStepEdge>;
     getAllEdges(): Record<string, string[]>;
     getStep(id: string): Workflow["steps"][number];
-    getRoot(): (l$1.Trigger & {
-        openfn?: OpenfnMeta;
-    }) | undefined;
-    getUUID(id: any): string;
-    toJSON(): JSON.Object;
+    getRoot(): WithMeta<l.Job & l.Trigger> | undefined;
+    getUUID(id: string): string;
+    toJSON(): Object;
     getUUIDMap(): Record<string, string>;
     getVersionHash(): string;
     pushHistory(versionHash: string): void;
     canMergeInto(target: Workflow): boolean;
 }
 
-type FileFormats$1 = 'yaml' | 'json';
-interface WorkspaceConfig {
-    dirs: {
-        workflows: string;
-        projects: string;
-    };
-    formats: {
-        openfn: FileFormats$1;
-        project: FileFormats$1;
-        workflow: FileFormats$1;
-    };
-}
+type fromAppStateConfig = Partial<l.WorkspaceConfig> & {
+    format?: 'yaml' | 'json';
+};
 
-type FromPathConfig = {
-    config: WorkspaceConfig;
+type FromPathConfig = l.WorkspaceConfig & {
+    format: 'json' | 'yaml';
 };
 
 type FromFsConfig = {
     root: string;
 };
 
-type MergeProjectOptions = Partial<{
+type MergeProjectOptions = {
     workflowMappings: Record<string, string>;
     removeUnmapped: boolean;
     force: boolean;
-}>;
+};
 
 declare class Workspace {
-    config?: WorkspaceConfig;
-    projectMeta: ProjectMeta;
+    config: l.WorkspaceConfig;
+    activeProject?: l.ProjectMeta;
     private projects;
     private projectPaths;
     private isValid;
     constructor(workspacePath: string);
     loadProject(): void;
     list(): Project[];
+    /** Get a project by its id or UUID */
     get(id: string): Project | undefined;
     getProjectPath(id: string): string | undefined;
     getActiveProject(): Project | undefined;
-    getConfig(): Partial<WorkspaceConfig>;
-    get activeProjectId(): any;
+    getConfig(): Partial<l.WorkspaceConfig>;
+    get activeProjectId(): unknown;
     get valid(): boolean;
 }
 
-type RepoOptions = {
-    /**default workflow root when serializing to fs (relative to openfn.yaml) */
-    workflowRoot?: string;
-    formats: {
-        openfn: FileFormats;
-        workflow: FileFormats;
-        project: FileFormats;
+type UUIDMap = {
+    [workflowId: string]: {
+        self?: UUID;
+        children: {
+            [nodeId: string]: UUID;
+        };
     };
 };
 declare class Project {
-    /** project name */
+    /** Human readable project name. This corresponds to the label in Lightning */
     name?: string;
+    /** Project id. Must be url safe. May be derived from the name. NOT a UUID */
+    id: string;
     description?: string;
     history: string[];
     workflows: Workflow[];
     options: any;
     meta: any;
-    openfn?: l.ProjectConfig;
+    openfn?: l__default.ProjectMeta;
     workspace?: Workspace;
-    config: WorkspaceConfig;
+    config: l__default.WorkspaceConfig;
     collections: any;
-    static from(type: 'state', data: any, options: Partial<l.ProjectConfig>): Project;
-    static from(type: 'fs', options: FromFsConfig): Project;
+    credentials: string[];
+    static from(type: 'state', data: Provisioner.Project, meta?: Partial<l__default.ProjectMeta>, config?: fromAppStateConfig): Promise<Project>;
+    static from(type: 'fs', options: FromFsConfig): Promise<Project>;
     static from(type: 'path', data: string, options?: {
         config?: FromPathConfig;
-    }): Project;
-    static diff(a: Project, b: Project): void;
-    static merge(source: Project, target: Project, options: MergeProjectOptions): Project;
-    constructor(data: l.Project, repoConfig?: RepoOptions);
+    }): Promise<Project>;
+    static merge(source: Project, target: Project, options?: Partial<MergeProjectOptions>): Project;
+    constructor(data: Partial<l__default.Project>, config?: Partial<l__default.WorkspaceConfig>);
     setConfig(config: Partial<WorkspaceConfig>): void;
     serialize(type?: 'json' | 'yaml' | 'fs' | 'state', options?: any): any;
-    getVersionHash(): void;
     getWorkflow(idOrName: string): Workflow | undefined;
     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;
-    }): {};
+    getUUIDMap(): UUIDMap;
 }
 
 declare function yamlToJson(y: string): any;
-declare function jsonToYaml(json: string | JSONObject): string;
+declare function jsonToYaml(json: string | Object): string;
 
 type GenerateWorkflowOptions = {
     name: string;
@@ -138,6 +119,7 @@ type GenerateWorkflowOptions = {
 };
 type GenerateProjectOptions = GenerateWorkflowOptions & {
     uuidMap: Array<Record<string, string>>;
+    uuid?: string | number;
 };
 /**
  * Generate a Workflow from a simple text based representation

package/dist/index.js

@@ -4,9 +4,12 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/Project.ts
+import { humanId } from "human-id";
+
 // src/util/slugify.ts
 function slugify(text) {
-  return text?.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase();
+  return text?.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase() ?? "";
 }
 
 // src/util/version.ts
@@ -22,7 +25,7 @@ var generateHash = (workflow, source = "cli") => {
     "name",
     "adaptors",
     "adaptor",
-    // there's ao adaptor & adaptors key in steps somehow.
+    // there's both adaptor & adaptors key in steps somehow
     "expression",
     "configuration",
     // assumes a string credential id
@@ -52,12 +55,13 @@ var generateHash = (workflow, source = "cli") => {
       }
     });
     if (step.next && Array.isArray(step.next)) {
-      const edges = step.next.slice().sort((a, b) => {
+      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 edges) {
+      for (const edge of step.next) {
         edgeKeys.forEach((key) => {
           if (isDefined(edge[key])) {
             parts.push(key, serializeValue(edge[key]));
@@ -86,6 +90,8 @@ var Workflow = class {
   name;
   id;
   openfn;
+  options;
+  // TODO
   constructor(workflow) {
     this.index = {
       steps: {},
@@ -111,13 +117,14 @@ var Workflow = class {
     }
     this.openfn = openfn;
     this.options = options;
-    this.#buildIndex();
+    this._buildIndex();
   }
   get steps() {
     return this.workflow.steps;
   }
-  #buildIndex() {
-    for (const s of this.workflow.steps) {
+  _buildIndex() {
+    for (const step of this.workflow.steps) {
+      const s = step;
       this.index.steps[s.id] = s;
       this.index.uuid[s.id] = s.openfn?.uuid;
       if (s.openfn?.uuid) {
@@ -171,7 +178,8 @@ var Workflow = class {
   }
   getAllEdges() {
     const edges = {};
-    for (const step of this.steps) {
+    for (const s of this.steps) {
+      const step = s;
       const next = typeof step.next === "string" ? { [step.next]: true } : step.next || {};
       for (const toNode of Object.keys(next)) {
         if (!Array.isArray(edges[step.id]))
@@ -215,14 +223,10 @@ var Workflow = class {
   }
   // return true if the current workflow can be merged into the target workflow without losing any changes
   canMergeInto(target) {
-    const thisHistory = this.workflow.history?.concat(this.getVersionHash());
-    const targetHistory = target.workflow.history?.concat(
-      target.getVersionHash()
-    );
+    const thisHistory = this.workflow.history?.concat(this.getVersionHash()) ?? [];
+    const targetHistory = target.workflow.history?.concat(target.getVersionHash()) ?? [];
     const targetHead = targetHistory[targetHistory.length - 1];
-    if (thisHistory.indexOf(targetHead) > -1)
-      return true;
-    return false;
+    return thisHistory.indexOf(targetHead) > -1;
   }
 };
 var Workflow_default = Workflow;
@@ -240,11 +244,12 @@ function to_json_default(project) {
   return {
     // There must be a better way to do this?
     // Do we just serialize all public fields?
+    id: project.id,
     name: project.name,
     description: project.description,
     config: project.config,
     meta: project.meta,
-    workflows: project.workflows,
+    workflows: project.workflows.map((w) => w.toJSON()),
     collections: project.collections,
     credentials: project.credentials,
     openfn: project.openfn,
@@ -252,6 +257,10 @@ function to_json_default(project) {
   };
 }
 
+// src/serialize/to-app-state.ts
+import { pick, omitBy, isNil } from "lodash-es";
+import { randomUUID } from "node:crypto";
+
 // src/util/rename-keys.ts
 function renameKeys(props = {}, keyMap) {
   return Object.fromEntries(
@@ -277,19 +286,16 @@ 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 state = {
-    id,
-    name: project.name,
-    description: project.description,
-    project_credentials: project.credentials,
-    collections: project.collections,
-    ...rest,
-    ...project.options,
-    workflows: project.workflows.map(mapWorkflow)
-  };
+  const { uuid, endpoint, env, ...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);
   const shouldReturnYaml = options.format === "yaml" || !options.format && project.config.formats.project === "yaml";
   if (shouldReturnYaml) {
     return jsonToYaml(state);
@@ -304,11 +310,15 @@ var mapWorkflow = (workflow) => {
   const wfState = {
     ...originalOpenfnProps,
     id: workflow.openfn?.uuid ?? randomUUID(),
-    name: workflow.name,
     jobs: [],
     triggers: [],
-    edges: []
+    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 ??= {};
@@ -318,7 +328,7 @@ var mapWorkflow = (workflow) => {
     return obj;
   }, {});
   workflow.steps.forEach((s) => {
-    let isTrigger;
+    let isTrigger = false;
     let node;
     if (s.type && !s.expression) {
       isTrigger = true;
@@ -328,23 +338,28 @@ var mapWorkflow = (workflow) => {
       };
       wfState.triggers.push(node);
     } else {
-      node = {
-        name: s.name,
-        body: s.expression,
-        adaptor: s.adaptor,
-        ...renameKeys(s.openfn, { uuid: "id" })
-      };
+      node = omitBy(pick(s, ["name", "adaptor"]), isNil);
+      const { uuid: uuid2, ...otherOpenFnProps } = s.openfn ?? {};
+      node.id = uuid2;
+      Object.assign(node, otherOpenFnProps);
+      if (s.expression) {
+        node.body = s.expression;
+      }
+      node.project_credential_id = s.openfn?.project_credential_id ?? null;
+      node.keychain_credential_id = null;
       wfState.jobs.push(node);
     }
     Object.keys(s.next ?? {}).forEach((next) => {
       const rules = s.next[next];
+      const { uuid: uuid2, ...otherOpenFnProps } = rules.openfn ?? {};
       const e = {
-        id: rules.openfn?.uuid ?? randomUUID(),
+        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 {
@@ -368,13 +383,12 @@ import nodepath from "path";
 // src/util/config.ts
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { pickBy, isNil } from "lodash-es";
+import { pickBy, isNil as isNil2 } from "lodash-es";
 var buildConfig = (config = {}) => ({
   ...config,
   dirs: {
-    projects: ".projects",
-    // TODO change to projects
-    workflows: "workflows"
+    projects: config.dirs?.projects ?? ".projects",
+    workflows: config.dirs?.workflows ?? "workflows"
   },
   formats: {
     openfn: config.formats?.openfn ?? "yaml",
@@ -384,7 +398,8 @@ var buildConfig = (config = {}) => ({
 });
 var extractConfig = (source) => {
   const project = {
-    ...source.openfn || {}
+    ...source.openfn || {},
+    id: source.id
   };
   const workspace = {
     ...source.config
@@ -429,7 +444,7 @@ var loadWorkspaceFile = (contents, format = "yaml") => {
         formats,
         dirs
       },
-      (value) => !isNil(value)
+      (value) => !isNil2(value)
     );
   } else {
     project = json.project ?? {};
@@ -438,13 +453,10 @@ var loadWorkspaceFile = (contents, format = "yaml") => {
   return { project, workspace };
 };
 var findWorkspaceFile = (dir = ".") => {
-  console.log({ dir });
   let content, type;
   try {
     type = "yaml";
-    console.log(path.resolve(path.join(dir, "openfn.yaml")));
     content = readFileSync(path.resolve(path.join(dir, "openfn.yaml")), "utf8");
-    console.log({ content });
   } catch (e) {
     try {
       type = "json";
@@ -453,7 +465,6 @@ var findWorkspaceFile = (dir = ".") => {
         content = JSON.parse(file);
       }
     } catch (e2) {
-      console.log(e2);
       throw e2;
     }
   }
@@ -479,13 +490,13 @@ function to_fs_default(project) {
   }
   return files;
 }
-var extractWorkflow = (project, workflowId2) => {
+var extractWorkflow = (project, workflowId) => {
   const format = project.config.formats.workflow;
-  const workflow = project.getWorkflow(workflowId2);
+  const workflow = project.getWorkflow(workflowId);
   if (!workflow) {
-    throw new Error(`workflow not found: ${workflowId2}`);
+    throw new Error(`workflow not found: ${workflowId}`);
   }
-  const root = project.config.dirs.workflow ?? project.config.workflowRoot ?? "workflows/";
+  const root = project.config.dirs.workflows ?? project.config.workflowRoot ?? "workflows/";
   const path5 = nodepath.join(root, workflow.id, workflow.id);
   const wf = {
     id: workflow.id,
@@ -503,17 +514,17 @@ var extractWorkflow = (project, workflowId2) => {
   };
   return handleOutput(wf, path5, format);
 };
-var extractStep = (project, workflowId2, stepId) => {
-  const workflow = project.getWorkflow(workflowId2);
+var extractStep = (project, workflowId, stepId) => {
+  const workflow = project.getWorkflow(workflowId);
   if (!workflow) {
-    throw new Error(`workflow not found: ${workflowId2}`);
+    throw new Error(`workflow not found: ${workflowId}`);
   }
   const step = workflow.steps.find((s) => s.id === stepId);
   if (!step) {
     throw new Error(`step not found: ${stepId}`);
   }
   if (step.expression) {
-    const root = project.config?.workflowRoot ?? "workflows/";
+    const root = project.config?.dirs.workflows ?? project.config?.workflowRoot ?? "workflows/";
     const path5 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
     const content = step.expression;
     return { path: path5, content };
@@ -533,17 +544,18 @@ var handleOutput = (data, filePath, format) => {
 };
 
 // src/parse/from-app-state.ts
-function slugify2(text) {
-  return text.replace(/\W/g, " ").trim().replace(/\s+/g, "-").toLowerCase();
-}
-var from_app_state_default = (state, config) => {
+var from_app_state_default = (state, meta, config = {}) => {
+  let stateJson;
   if (typeof state === "string") {
-    if (config?.format === "yaml") {
-      state = yamlToJson(state);
+    if (config.format === "yaml") {
+      stateJson = yamlToJson(state);
     } else {
-      state = JSON.parse(state);
+      stateJson = JSON.parse(state);
     }
+  } else {
+    stateJson = state;
   }
+  delete config.format;
   const {
     id,
     name,
@@ -554,27 +566,25 @@ var from_app_state_default = (state, config) => {
     inserted_at,
     updated_at,
     ...options
-  } = state;
+  } = stateJson;
   const proj = {
     name,
-    description,
+    description: description ?? void 0,
     collections,
     credentials,
-    options
+    options,
+    config
   };
+  const { id: _ignore, ...restMeta } = meta;
   proj.openfn = {
+    // @ts-ignore
     uuid: id,
-    name,
-    endpoint: config.endpoint,
-    env: config.env,
+    ...restMeta,
     inserted_at,
     updated_at
   };
-  proj.meta = {
-    fetched_at: config.fetchedAt
-  };
-  proj.workflows = state.workflows.map(mapWorkflow2);
-  return new Project(proj, config?.config);
+  proj.workflows = stateJson.workflows.map(mapWorkflow2);
+  return new Project(proj, config);
 };
 var mapTriggerEdgeCondition = (edge) => {
   const e = {
@@ -600,7 +610,7 @@ var mapWorkflow2 = (workflow) => {
     openfn: renameKeys(remoteProps, { id: "uuid" })
   };
   if (workflow.name) {
-    mapped.id = slugify2(workflow.name);
+    mapped.id = slugify(workflow.name);
   }
   workflow.triggers.forEach((trigger) => {
     const { type, ...otherProps } = trigger;
@@ -616,7 +626,7 @@ var mapWorkflow2 = (workflow) => {
         if (!target) {
           throw new Error(`Failed to find ${edge.target_job_id}`);
         }
-        obj[slugify2(target.name)] = mapTriggerEdgeCondition(edge);
+        obj[slugify(target.name)] = mapTriggerEdgeCondition(edge);
         return obj;
       }, {})
     });
@@ -627,16 +637,17 @@ var mapWorkflow2 = (workflow) => {
     );
     const { body: expression, name: name2, adaptor, ...remoteProps2 } = step;
     const s = {
-      id: slugify2(name2),
+      id: slugify(name2),
       name: name2,
       expression,
       adaptor,
+      // TODO is this wrong?
       openfn: renameKeys(remoteProps2, { id: "uuid" })
     };
     if (outboundEdges.length) {
       s.next = outboundEdges.reduce((next, edge) => {
         const target = jobs.find((j) => j.id === edge.target_job_id);
-        next[slugify2(target.name)] = mapTriggerEdgeCondition(edge);
+        next[slugify(target.name)] = mapTriggerEdgeCondition(edge);
         return next;
       }, {});
     }
@@ -648,13 +659,10 @@ var mapWorkflow2 = (workflow) => {
 // src/parse/from-path.ts
 import { extname } from "node:path";
 import { readFile } from "node:fs/promises";
-var from_path_default = async (path5, options = {}) => {
+import { omit } from "lodash-es";
+var from_path_default = async (path5, config = {}) => {
   const ext = extname(path5).toLowerCase();
   const source = await readFile(path5, "utf8");
-  const config = {
-    format: null,
-    config: options.config
-  };
   let state;
   if (ext === ".json") {
     config.format = "json";
@@ -665,7 +673,8 @@ var from_path_default = async (path5, options = {}) => {
   } else {
     throw new Error(`Cannot load a project from a ${ext} file`);
   }
-  return from_app_state_default(state, config);
+  const meta = {};
+  return from_app_state_default(state, meta, omit(config, ["format"]));
 };
 
 // src/parse/from-fs.ts
@@ -687,18 +696,18 @@ var get_identifier_default = (config = {}) => {
 };
 
 // src/parse/from-fs.ts
-var parseProject = async (options = {}) => {
+var parseProject = async (options) => {
   const { root } = options;
   const { type, content } = findWorkspaceFile(root);
   const context = loadWorkspaceFile(content, type);
   const config = buildConfig(context.workspace);
-  let state;
+  let state = null;
   const identifier = get_identifier_default({
     endpoint: context.project?.endpoint,
     env: context.project?.env
   });
   try {
-    const format = config.formats?.project ?? config.formats?.projects ?? "yaml";
+    const format = config.formats?.project ?? config.formats?.project ?? "yaml";
     const statePath = path2.join(
       root,
       config.dirs?.projects ?? ".projects",
@@ -710,6 +719,7 @@ var parseProject = async (options = {}) => {
     console.warn(`Failed to find state file for ${identifier}`);
   }
   const proj = {
+    name: state?.name,
     openfn: context.project,
     config,
     workflows: []
@@ -720,7 +730,6 @@ var parseProject = async (options = {}) => {
   const candidateWfs = await glob(pattern, {
     ignore: ["**node_modules/**", "**tmp**"]
   });
-  const workflows = [];
   for (const filePath of candidateWfs) {
     const candidate = await fs.readFile(filePath, "utf-8");
     try {
@@ -729,7 +738,7 @@ var parseProject = async (options = {}) => {
         const wfState = (state && state.getWorkflow(wf.id)) ?? {};
         wf.openfn = {
           uuid: wfState.openfn?.uuid ?? null
-          // TODO do we need to transfer more stuff?
+          // TODO do we need to transfer more stuff? Options maybe?
         };
         for (const step of wf.steps) {
           if (step.expression && step.expression.endsWith(".js")) {
@@ -781,9 +790,7 @@ var getUuidForStep = (project, workflow, stepId) => {
 var getUuidForEdge = (project, workflow, from, to) => {
   const wf = typeof workflow === "string" ? project.getWorkflow(workflow) : workflow;
   if (!wf) {
-    throw new Error(
-      `Workflow "${workflowId} 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 === from) {
@@ -802,43 +809,48 @@ var getUuidForEdge = (project, workflow, from, to) => {
 import { defaultsDeep, isEmpty } from "lodash-es";
 
 // src/util/base-merge.ts
-import { pick, assign } from "lodash-es";
+import { pick as pick2, assign } from "lodash-es";
 function baseMerge(target, source, sourceKeys, assigns = {}) {
-  const pickedSource = sourceKeys ? pick(source, sourceKeys) : source;
+  const pickedSource = sourceKeys ? pick2(source, sourceKeys) : source;
   return assign(target, { ...pickedSource, ...assigns });
 }
 
 // src/merge/merge-node.ts
+var clone2 = (obj) => JSON.parse(JSON.stringify(obj));
 function mergeWorkflows(source, target, mappings) {
   const targetNodes = {};
-  for (const tstep2 of target.steps)
-    targetNodes[tstep2.openfn.uuid || tstep2.id] = tstep2;
+  for (const targetStep of target.steps) {
+    targetNodes[targetStep.openfn?.uuid || targetStep.id] = targetStep;
+  }
   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") {
+  for (const sourceStep of source.steps) {
+    let newNode = clone2(sourceStep);
+    if (sourceStep.id in mappings.nodes) {
+      const preservedId = mappings.nodes[sourceStep.id];
+      const toNodeIds = Object.keys(
+        typeof sourceStep.next === "string" ? { [sourceStep.next]: true } : sourceStep.next || {}
+      );
+      for (const toNode of toNodeIds) {
+        const key = sourceStep.id + "-" + toNode;
+        if (key in mappings.edges) {
           const preservedEdgeId = mappings.edges[key];
-          const toEdge = sstep.next?.[toNode] || {};
-          preservedEdgeIds[toNode] = sstep.next[toNode] = {
-            ...toEdge,
-            openfn: { ...toEdge?.openfn || {}, uuid: preservedEdgeId }
+          const edge = sourceStep.next?.[toNode] || {};
+          sourceStep.next[toNode] = {
+            ...edge,
+            openfn: Object.assign({}, edge?.openfn, {
+              uuid: preservedEdgeId
+            })
           };
         }
       }
-      newNode = baseMerge(targetNodes[preservedId], sstep, [
+      newNode = baseMerge(targetNodes[preservedId], sourceStep, [
         "id",
         "name",
+        // @ts-ignore
         "adaptor",
+        "adaptors",
         "expression",
-        "next",
-        "previous"
+        "next"
       ]);
     } else {
     }
@@ -962,7 +974,7 @@ function findBestMatch(sourceStep, candidates, sourceEdges, targetEdges, getMapp
   }
   return null;
 }
-function mapEdges(sourceEdges, targetEdges, idMap, getTargetUUID) {
+function mapEdges(sourceEdges, _targetEdges, idMap, getTargetUUID) {
   const edgeMapping = {};
   for (const [parentId, children] of Object.entries(sourceEdges)) {
     for (const childId of children) {
@@ -978,7 +990,7 @@ function mapEdges(sourceEdges, targetEdges, idMap, getTargetUUID) {
   return edgeMapping;
 }
 function getStepUuid(step) {
-  return step?.openfn?.uuid || step.id;
+  return step?.openfn?.uuid;
 }
 function mapStepsById(source, target) {
   const targetIndex = {};
@@ -1083,8 +1095,7 @@ function mapStepByChildren(sourceStep, candidates, sourceEdges, targetEdges, get
   };
 }
 function mapStepByExpression(sourceStep, candidates) {
-  const expression = sourceStep.expression;
-  return findByExpression(expression, candidates);
+  return findByExpression(sourceStep.expression, candidates);
 }
 
 // src/util/get-duplicates.ts
@@ -1102,15 +1113,20 @@ function getDuplicates(arr) {
 }
 
 // src/merge/merge-project.ts
-function merge(source, target, options) {
+var UnsafeMergeError = class extends Error {
+};
+function merge(source, target, opts) {
   const defaultOptions = {
     workflowMappings: {},
     removeUnmapped: false,
     force: true
   };
-  options = defaultsDeep(options, defaultOptions);
+  const options = defaultsDeep(
+    opts,
+    defaultOptions
+  );
   const dupTargetMappings = getDuplicates(
-    Object.values(options?.workflowMappings)
+    Object.values(options.workflowMappings ?? {})
   );
   if (dupTargetMappings.length) {
     throw new Error(
@@ -1132,11 +1148,11 @@ function merge(source, target, options) {
     const targetId = options.workflowMappings?.[sourceWorkflow.id] ?? sourceWorkflow.id;
     const targetWorkflow = target.getWorkflow(targetId);
     if (targetWorkflow && !sourceWorkflow.canMergeInto(targetWorkflow)) {
-      potentialConflicts[sourceWorkflow.name] = targetWorkflow?.name;
+      potentialConflicts[sourceWorkflow.id] = targetWorkflow?.id;
     }
   }
   if (Object.keys(potentialConflicts).length && !options?.force) {
-    throw new Error(
+    throw new UnsafeMergeError(
       `The below workflows can't be merged directly without losing data
 ${Object.entries(
         potentialConflicts
@@ -1151,6 +1167,7 @@ Pass --force to force the merge anyway`
       usedTargetIds.add(targetWorkflow.id);
       const mappings = map_uuids_default(sourceWorkflow, targetWorkflow);
       finalWorkflows.push(
+        // @ts-ignore
         mergeWorkflows(sourceWorkflow, targetWorkflow, mappings)
       );
     } else {
@@ -1165,7 +1182,9 @@ Pass --force to force the merge anyway`
     }
   }
   return new Project(
-    baseMerge(target, source, ["collections"], { workflows: finalWorkflows })
+    baseMerge(target, source, ["collections"], {
+      workflows: finalWorkflows
+    })
   );
 }
 
@@ -1175,10 +1194,12 @@ var Project = class {
   // what schema version is this?
   // And how are we tracking this?
   // version;
-  /** project name */
+  /** Human readable project name. This corresponds to the label in Lightning */
   name;
+  /** Project id. Must be url safe. May be derived from the name. NOT a UUID */
+  id;
   description;
-  // array of version shas
+  // array of version hashes
   history = [];
   workflows;
   // option strings saved by the app
@@ -1191,25 +1212,20 @@ var Project = class {
   openfn;
   workspace;
   config;
-  // 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 = {}) {
+  credentials;
+  static async from(type, data, ...rest) {
     if (type === "state") {
-      return from_app_state_default(data, options);
+      return from_app_state_default(data, rest[0], rest[1]);
     } else if (type === "fs") {
-      return parseProject(data, options);
+      return parseProject(data);
     } else if (type === "path") {
-      return from_path_default(data, options);
+      return from_path_default(data, rest[0]);
     }
     throw new Error(`Didn't recognize type ${type}`);
   }
   // Diff two projects
-  static diff(a, b) {
-  }
+  // /static diff(a: Project, b: Project) {}
   // Merge a source project (staging) into the target project (main)
   // Returns a new Project
   // TODO: throw if histories have diverged
@@ -1221,16 +1237,16 @@ var Project = class {
   // 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
   // TODO maybe the constructor is (data, Workspace)
-  constructor(data, repoConfig = {}) {
-    this.setConfig(repoConfig);
+  constructor(data, config) {
+    this.config = buildConfig(config);
+    this.id = data.id ?? (data.name ? slugify(data.name) : humanId({ separator: "-", capitalize: false }));
     this.name = data.name;
-    this.description = data.description;
+    this.description = data.description ?? void 0;
     this.openfn = data.openfn;
     this.options = data.options;
     this.workflows = data.workflows?.map(maybeCreateWorkflow) ?? [];
     this.collections = data.collections;
     this.credentials = data.credentials;
-    this.meta = data.meta;
   }
   setConfig(config) {
     this.config = buildConfig(config);
@@ -1241,16 +1257,9 @@ var Project = class {
     }
     throw new Error(`Cannot serialize ${type}`);
   }
-  // would like a better name for this
-  // stamp? id? sha?
-  // this builds a version string for the current state
-  getVersionHash() {
-  }
-  // what else might we need?
-  // get workflow by name or id
-  // this is fuzzy, but is that wrong?
+  // get workflow by name, id or uuid
   getWorkflow(idOrName) {
-    return this.workflows.find((wf) => wf.id == idOrName) || this.workflows.find((wf) => wf.name === idOrName);
+    return this.workflows.find((wf) => wf.id == idOrName) || this.workflows.find((wf) => wf.name === idOrName) || this.workflows.find((wf) => wf.openfn?.uuid === idOrName);
   }
   // it's the name of the project.yaml file
   // qualified name? Remote name? App name?
@@ -1259,8 +1268,7 @@ var Project = class {
     return get_identifier_default(this.openfn);
   }
   // Compare this project with another and return a diff
-  compare(proj) {
-  }
+  // compare(proj: Project) {}
   // find the UUID for a given node or edge
   // returns null if it doesn't exist
   getUUID(workflow, stepId, otherStep) {
@@ -1272,7 +1280,7 @@ var Project = class {
   /**
    * Returns a map of ids:uuids for everything in the project
    */
-  getUUIDMap(options = {}) {
+  getUUIDMap() {
     const result = {};
     for (const wf of this.workflows) {
       result[wf.id] = {
@@ -1305,10 +1313,10 @@ function pathExists(fpath, type) {
 }
 
 // src/Workspace.ts
-var PROJECT_EXTENSIONS = [".yaml", ".yml"];
 var Workspace = class {
+  // @ts-ignore config not defininitely assigned - it sure is
   config;
-  projectMeta;
+  activeProject;
   projects = [];
   projectPaths = /* @__PURE__ */ new Map();
   isValid = false;
@@ -1316,26 +1324,38 @@ var Workspace = class {
     let context;
     try {
       const { type, content } = findWorkspaceFile(workspacePath);
-      console.log(content);
       context = loadWorkspaceFile(content, type);
       this.isValid = true;
     } catch (e) {
-      console.log(e);
+      console.error(e);
       return;
     }
     this.config = buildConfig(context.workspace);
-    this.projectMeta = context.project;
+    this.activeProject = context.project;
     const projectsPath = path3.join(workspacePath, this.config.dirs.projects);
     if (this.isValid && pathExists(projectsPath, "directory")) {
+      const ext = `.${this.config.formats.project}`;
       const stateFiles = fs3.readdirSync(projectsPath).filter(
-        (fileName) => PROJECT_EXTENSIONS.includes(path3.extname(fileName)) && path3.parse(fileName).name !== "openfn"
+        (fileName) => path3.extname(fileName) === ext && path3.parse(fileName).name !== "openfn"
       );
       this.projects = stateFiles.map((file) => {
         const stateFilePath = path3.join(projectsPath, file);
-        const data = fs3.readFileSync(stateFilePath, "utf-8");
-        const project = from_app_state_default(data, { format: "yaml" });
-        this.projectPaths.set(project.name, stateFilePath);
-        return project;
+        try {
+          const data = fs3.readFileSync(stateFilePath, "utf-8");
+          const project = from_app_state_default(
+            data,
+            {},
+            {
+              ...this.config,
+              format: this.config?.formats.project
+            }
+          );
+          this.projectPaths.set(project.id, stateFilePath);
+          return project;
+        } catch (e) {
+          console.warn(`Failed to load project from ${stateFilePath}`);
+          console.warn(e);
+        }
       }).filter((s) => s);
     }
   }
@@ -1349,15 +1369,15 @@ var Workspace = class {
   list() {
     return this.projects;
   }
-  // TODO clear up name/id confusion
+  /** Get a project by its id or UUID */
   get(id) {
-    return this.projects.find((p) => p.name === id);
+    return this.projects.find((p) => p.id === id) ?? this.projects.find((p) => p.openfn?.uuid === id);
   }
   getProjectPath(id) {
     return this.projectPaths.get(id);
   }
   getActiveProject() {
-    return this.projects.find((p) => p.name === this.projectMeta?.name);
+    return this.projects.find((p) => p.id === this.activeProject?.id) ?? this.projects.find((p) => p.openfn?.uuid === this.activeProject?.uuid);
   }
   // TODO this needs to return default values
   // We should always rely on the workspace to load these values
@@ -1365,7 +1385,7 @@ var Workspace = class {
     return this.config;
   }
   get activeProjectId() {
-    return this.projectMeta?.name;
+    return this.activeProject?.id;
   }
   get valid() {
     return this.isValid;
@@ -1377,6 +1397,7 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import path4 from "node:path";
 import { readFileSync as readFileSync2 } from "node:fs";
 import { grammar } from "ohm-js";
+import { isNil as isNil3 } from "lodash-es";
 var parser;
 var initOperations = (options = {}) => {
   let nodes = {};
@@ -1496,6 +1517,10 @@ function generateWorkflow(def, options = {}) {
   if (!parser) {
     parser = createParser();
   }
+  let uuid;
+  if (options.openfnUuid) {
+    uuid = options.uuidSeed ? options.uuidSeed++ : randomUUID2();
+  }
   const raw = parser.parse(def, options);
   if (!raw.name) {
     raw.name = "Workflow";
@@ -1503,9 +1528,12 @@ function generateWorkflow(def, options = {}) {
   if (!raw.id) {
     raw.id = "workflow";
   }
-  if (options.openfnUuid) {
+  if (options.uuidMap && raw.id in options.uuidMap) {
+    uuid = options.uuidMap[raw.id];
+  }
+  if (!isNil3(uuid) && options.openfnUuid) {
     raw.openfn ??= {};
-    raw.openfn.uuid = randomUUID2();
+    raw.openfn.uuid = uuid;
   }
   const wf = new Workflow_default(raw);
   return wf;
@@ -1520,7 +1548,9 @@ function generateProject(name, workflowDefs, options = {}) {
   return new Project_default({
     name,
     workflows,
-    openfn: options.openfnUuid && { uuid: randomUUID2() }
+    openfn: {
+      uuid: options.uuid ?? (options.openfnUuid ? randomUUID2() : void 0)
+    }
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/project",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Read, serialize, replicate and sync OpenFn projects",
   "type": "module",
   "exports": {
@@ -27,13 +27,15 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
+    "@types/lodash-es": "^4.17.12",
     "glob": "^11.0.2",
+    "human-id": "^4.1.1",
     "lodash": "^4.17.21",
     "lodash-es": "^4.17.21",
     "ohm-js": "^17.2.1",
     "yaml": "^2.2.2",
-    "@openfn/lexicon": "^1.2.5",
-    "@openfn/logger": "1.0.6"
+    "@openfn/logger": "1.0.6",
+    "@openfn/lexicon": "^1.2.6"
   },
   "files": [
     "dist",