@openfn/project 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as l from '@openfn/lexicon';
+import * as l$1 from '@openfn/lexicon';
 
 type OpenfnMeta = {
     uuid?: string;
@@ -8,7 +8,7 @@ type WithMeta<T> = T & {
 };
 declare class Workflow {
     #private;
-    workflow: l.Workflow;
+    workflow: l$1.Workflow;
     index: {
         steps: {};
         edges: {};
@@ -18,37 +18,27 @@ declare class Workflow {
     name?: string;
     id: string;
     openfn: OpenfnMeta;
-    constructor(workflow: l.Workflow);
-    get steps(): WithMeta<l.Job | l.Trigger>[];
-    set(id: string, props: Parital<l.Job, l.Edge>): this;
-    get(id: any): WithMeta<l.Step | l.Trigger | l.Edge>;
+    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.ConditionalStepEdge>;
+    getEdge(from: any, to: any): WithMeta<l$1.ConditionalStepEdge>;
     getAllEdges(): Record<string, string[]>;
     getStep(id: string): Workflow["steps"][number];
-    getRoot(): (l.Trigger & {
+    getRoot(): (l$1.Trigger & {
         openfn?: OpenfnMeta;
     }) | undefined;
     getUUID(id: any): string;
     toJSON(): JSON.Object;
     getUUIDMap(): Record<string, string>;
     getVersionHash(): string;
+    pushHistory(versionHash: string): void;
+    canMergeInto(target: Workflow): boolean;
 }
 
-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;
+interface WorkspaceConfig {
     dirs: {
         workflows: string;
         projects: string;
@@ -58,44 +48,64 @@ interface OpenfnConfig {
         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;
-    formats: {
-        openfn: FileFormats;
-        workflow: FileFormats;
-        project: FileFormats;
-    };
+
+type FromPathConfig = {
+    config: WorkspaceConfig;
 };
+
+type FromFsConfig = {
+    root: string;
+};
+
+type MergeProjectOptions = Partial<{
+    workflowMappings: Record<string, string>;
+    removeUnmapped: boolean;
+    force: boolean;
+}>;
+
+declare class Workspace {
+    config?: WorkspaceConfig;
+    activeProject: 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;
+    get valid(): boolean;
+}
+
 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;
-    repo?: Required<RepoOptions>;
+    workspace?: Workspace;
+    config: WorkspaceConfig;
     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: string, options?: {
-        config?: Partial<OpenfnConfig>;
+        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);
+    constructor(data: l.Project, config?: RepoOptions);
+    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;
@@ -109,21 +119,6 @@ declare class Project {
     }): {};
 }
 
-declare class Workspace {
-    private config?;
-    private projects;
-    private projectPaths;
-    private isValid;
-    constructor(workspacePath: string);
-    list(): Project[];
-    get(id: string): Project | undefined;
-    getProjectPath(id: string): string | undefined;
-    getActiveProject(): Project | undefined;
-    getConfig(): Partial<OpenfnConfig>;
-    get activeProjectId(): string | undefined;
-    get valid(): boolean;
-}
-
 declare function yamlToJson(y: string): any;
 declare function jsonToYaml(json: string | JSONObject): string;
 

package/dist/index.js

@@ -4,6 +4,9 @@ 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();
@@ -98,6 +101,7 @@ var Workflow = class {
       // uuid to ids
     };
     this.workflow = clone(workflow);
+    this.workflow.history = workflow.history?.length ? workflow.history : [];
     const { id, name, openfn, steps, ...options } = workflow;
     if (!(id || name)) {
       throw new Error("A Workflow MUST have a name or id");
@@ -209,6 +213,20 @@ var Workflow = class {
   getVersionHash() {
     return generateHash(this);
   }
+  pushHistory(versionHash) {
+    this.workflow.history?.push(versionHash);
+  }
+  // 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 targetHead = targetHistory[targetHistory.length - 1];
+    if (thisHistory.indexOf(targetHead) > -1)
+      return true;
+    return false;
+  }
 };
 var Workflow_default = Workflow;
 
@@ -227,7 +245,7 @@ function to_json_default(project) {
     // Do we just serialize all public fields?
     name: project.name,
     description: project.description,
-    repo: project.repo,
+    config: project.config,
     meta: project.meta,
     workflows: project.workflows,
     collections: project.collections,
@@ -275,7 +293,7 @@ function to_app_state_default(project, options = {}) {
     ...project.options,
     workflows: project.workflows.map(mapWorkflow)
   };
-  const shouldReturnYaml = options.format === "yaml" || !options.format && project.repo.formats.project === "yaml";
+  const shouldReturnYaml = options.format === "yaml" || !options.format && project.config.formats.project === "yaml";
   if (shouldReturnYaml) {
     return jsonToYaml(state);
   }
@@ -326,7 +344,9 @@ var mapWorkflow = (workflow) => {
       const e = {
         id: rules.openfn?.uuid ?? randomUUID(),
         target_job_id: lookup[next],
-        enabled: !rules.disabled
+        enabled: !rules.disabled,
+        source_trigger_id: null
+        // lightning complains if this isn't set, even if its falsy :(
       };
       if (isTrigger) {
         e.source_trigger_id = node.id;
@@ -347,32 +367,127 @@ var mapWorkflow = (workflow) => {
 
 // src/serialize/to-fs.ts
 import nodepath from "path";
+
+// src/util/config.ts
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { pickBy, isNil } from "lodash-es";
+var buildConfig = (config = {}) => ({
+  ...config,
+  dirs: {
+    projects: ".projects",
+    // TODO change to projects
+    workflows: "workflows"
+  },
+  formats: {
+    openfn: config.formats?.openfn ?? "yaml",
+    project: config.formats?.project ?? "yaml",
+    workflow: config.formats?.workflow ?? "yaml"
+  }
+});
+var extractConfig = (source) => {
+  const project = {
+    ...source.openfn || {},
+    id: source.id
+  };
+  const workspace = {
+    ...source.config
+  };
+  const content = { project, workspace };
+  const format = workspace.formats.openfn;
+  if (format === "yaml") {
+    return {
+      path: "openfn.yaml",
+      content: jsonToYaml(content)
+    };
+  }
+  return {
+    path: "openfn.json",
+    content: JSON.stringify(content, null, 2)
+  };
+};
+var loadWorkspaceFile = (contents, format = "yaml") => {
+  let project, workspace;
+  let json = contents;
+  if (format === "yaml") {
+    json = yamlToJson(contents) ?? {};
+  } else if (typeof contents === "string") {
+    json = JSON.parse(contents);
+  }
+  const legacy = !json.workspace && !json.projects;
+  if (legacy) {
+    project = json.project ?? {};
+    if (json.name) {
+      project.name = json.name;
+    }
+    const {
+      formats,
+      dirs,
+      project: _,
+      name,
+      ...rest
+    } = json;
+    workspace = pickBy(
+      {
+        ...rest,
+        formats,
+        dirs
+      },
+      (value) => !isNil(value)
+    );
+  } else {
+    project = json.project ?? {};
+    workspace = json.workspace ?? {};
+  }
+  return { project, workspace };
+};
+var findWorkspaceFile = (dir = ".") => {
+  let content, type;
+  try {
+    type = "yaml";
+    content = readFileSync(path.resolve(path.join(dir, "openfn.yaml")), "utf8");
+  } catch (e) {
+    try {
+      type = "json";
+      const file = readFileSync(path.join(dir, "openfn.json"), "utf8");
+      if (file) {
+        content = JSON.parse(file);
+      }
+    } catch (e2) {
+      console.log(e2);
+      throw e2;
+    }
+  }
+  return { content, type };
+};
+
+// src/serialize/to-fs.ts
 var stringify = (json) => JSON.stringify(json, null, 2);
 function to_fs_default(project) {
   const files = {};
-  const { path: path4, content } = extractRepoConfig(project);
-  files[path4] = content;
+  const { path: path5, content } = extractConfig(project);
+  files[path5] = content;
   for (const wf of project.workflows) {
-    const { path: path5, content: content2 } = extractWorkflow(project, wf.id);
-    files[path5] = content2;
+    const { path: path6, content: content2 } = extractWorkflow(project, wf.id);
+    files[path6] = content2;
     for (const s of wf.steps) {
       const result = extractStep(project, wf.id, s.id);
       if (result) {
-        const { path: path6, content: content3 } = result;
-        files[path6] = content3;
+        const { path: path7, content: content3 } = result;
+        files[path7] = content3;
       }
     }
   }
   return files;
 }
 var extractWorkflow = (project, workflowId2) => {
-  const format = project.repo.formats.workflow;
+  const format = project.config.formats.workflow;
   const workflow = project.getWorkflow(workflowId2);
   if (!workflow) {
     throw new Error(`workflow not found: ${workflowId2}`);
   }
-  const root = project.repo?.workflowRoot ?? "workflows/";
-  const path4 = nodepath.join(root, workflow.id, workflow.id);
+  const root = project.config.dirs.workflow ?? project.config.workflowRoot ?? "workflows/";
+  const path5 = nodepath.join(root, workflow.id, workflow.id);
   const wf = {
     id: workflow.id,
     name: workflow.name,
@@ -387,7 +502,7 @@ var extractWorkflow = (project, workflowId2) => {
       return mapped;
     })
   };
-  return handleOutput(wf, path4, format);
+  return handleOutput(wf, path5, format);
 };
 var extractStep = (project, workflowId2, stepId) => {
   const workflow = project.getWorkflow(workflowId2);
@@ -400,31 +515,22 @@ var extractStep = (project, workflowId2, stepId) => {
   }
   if (step.expression) {
     const root = project.config?.workflowRoot ?? "workflows/";
-    const path4 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
+    const path5 = nodepath.join(root, `${workflow.id}/${step.id}.js`);
     const content = step.expression;
-    return { path: path4, content };
+    return { path: path5, content };
   }
 };
-var extractRepoConfig = (project) => {
-  const format = project.repo.formats.openfn;
-  const config = {
-    name: project.name,
-    ...project.repo,
-    project: project.openfn ?? {}
-  };
-  return handleOutput(config, "openfn", format);
-};
 var handleOutput = (data, filePath, format) => {
-  const path4 = `${filePath}.${format}`;
+  const path5 = `${filePath}.${format}`;
   let content;
   if (format === "json") {
-    content = stringify(data, null, 2);
+    content = stringify(data);
   } else if (format === "yaml") {
     content = jsonToYaml(data);
   } else {
     throw new Error(`Unrecognised format: ${format}`);
   }
-  return { path: path4, content };
+  return { path: path5, content };
 };
 
 // src/parse/from-app-state.ts
@@ -459,6 +565,7 @@ var from_app_state_default = (state, config) => {
   };
   proj.openfn = {
     uuid: id,
+    name,
     endpoint: config.endpoint,
     env: config.env,
     inserted_at,
@@ -468,7 +575,7 @@ var from_app_state_default = (state, config) => {
     fetched_at: config.fetchedAt
   };
   proj.workflows = state.workflows.map(mapWorkflow2);
-  return new Project(proj, config?.repo);
+  return new Project(proj, config?.config);
 };
 var mapTriggerEdgeCondition = (edge) => {
   const e = {
@@ -542,13 +649,12 @@ var mapWorkflow2 = (workflow) => {
 // 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");
+var from_path_default = async (path5, options = {}) => {
+  const ext = extname(path5).toLowerCase();
+  const source = await readFile(path5, "utf8");
   const config = {
     format: null,
-    repo: options.repo ?? options.config
-    // TMP
+    config: options.config
   };
   let state;
   if (ext === ".json") {
@@ -565,7 +671,7 @@ var from_path_default = async (path4, options = {}) => {
 
 // src/parse/from-fs.ts
 import fs from "node:fs/promises";
-import path from "node:path";
+import path2 from "node:path";
 import { glob } from "glob";
 
 // src/util/get-identifier.ts
@@ -584,34 +690,17 @@ var get_identifier_default = (config = {}) => {
 // src/parse/from-fs.ts
 var parseProject = async (options = {}) => {
   const { root } = options;
-  const proj = {};
-  let config;
-  try {
-    const file = await fs.readFile(
-      path.resolve(path.join(root, "openfn.yaml")),
-      "utf8"
-    );
-    config = yamlToJson(file);
-  } catch (e) {
-    try {
-      const file = await fs.readFile(
-        path.join(root || ".", "openfn.json"),
-        "utf8"
-      );
-      config = JSON.parse(file);
-    } catch (e2) {
-      console.log(e2);
-      throw e2;
-    }
-  }
+  const { type, content } = findWorkspaceFile(root);
+  const context = loadWorkspaceFile(content, type);
+  const config = buildConfig(context.workspace);
   let state;
   const identifier = get_identifier_default({
-    endpoint: config.project?.endpoint,
-    env: config.project?.env
+    endpoint: context.project?.endpoint,
+    env: context.project?.env
   });
   try {
     const format = config.formats?.project ?? config.formats?.projects ?? "yaml";
-    const statePath = path.join(
+    const statePath = path2.join(
       root,
       config.dirs?.projects ?? ".projects",
       `${identifier}.${format}`
@@ -621,9 +710,12 @@ var parseProject = async (options = {}) => {
   } catch (e) {
     console.warn(`Failed to find state file for ${identifier}`);
   }
-  const { project: openfn, ...repo } = config;
-  proj.openfn = openfn;
-  proj.config = repo;
+  const proj = {
+    name: state?.name,
+    openfn: context.project,
+    config,
+    workflows: []
+  };
   const workflowDir = config.workflowRoot ?? config.dirs?.workflows ?? "workflows";
   const fileType = config.formats?.workflow ?? "yaml";
   const pattern = `${root}/${workflowDir}/*/*.${fileType}`;
@@ -639,12 +731,12 @@ 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")) {
-            const dir = path.dirname(filePath);
-            const exprPath = path.join(dir, step.expression);
+            const dir = path2.dirname(filePath);
+            const exprPath = path2.join(dir, step.expression);
             try {
               console.debug(`Loaded expression from ${exprPath}`);
               step.expression = await fs.readFile(exprPath, "utf-8");
@@ -663,15 +755,14 @@ var parseProject = async (options = {}) => {
             step.next[target].openfn = { uuid: uuid2 };
           }
         }
-        workflows.push(wf);
+        proj.workflows.push(wf);
       }
     } catch (e) {
       console.log(e);
       continue;
     }
   }
-  proj.workflows = workflows;
-  return new Project(proj, repo);
+  return new Project(proj, context.workspace);
 };
 
 // src/util/uuid.ts
@@ -1016,7 +1107,8 @@ function getDuplicates(arr) {
 function merge(source, target, options) {
   const defaultOptions = {
     workflowMappings: {},
-    removeUnmapped: false
+    removeUnmapped: false,
+    force: true
   };
   options = defaultsDeep(options, defaultOptions);
   const dupTargetMappings = getDuplicates(
@@ -1037,6 +1129,23 @@ function merge(source, target, options) {
       return true;
     return !!options?.workflowMappings[w.id];
   });
+  const potentialConflicts = {};
+  for (const sourceWorkflow of sourceWorkflows) {
+    const targetId = options.workflowMappings?.[sourceWorkflow.id] ?? sourceWorkflow.id;
+    const targetWorkflow = target.getWorkflow(targetId);
+    if (targetWorkflow && !sourceWorkflow.canMergeInto(targetWorkflow)) {
+      potentialConflicts[sourceWorkflow.name] = targetWorkflow?.name;
+    }
+  }
+  if (Object.keys(potentialConflicts).length && !options?.force) {
+    throw new Error(
+      `The below workflows can't be merged directly without losing data
+${Object.entries(
+        potentialConflicts
+      ).map(([from, to]) => `${from} \u2192 ${to}`).join("\n")}
+Pass --force to force the merge anyway`
+    );
+  }
   for (const sourceWorkflow of sourceWorkflows) {
     const targetId = options.workflowMappings?.[sourceWorkflow.id] ?? sourceWorkflow.id;
     const targetWorkflow = target.getWorkflow(targetId);
@@ -1064,24 +1173,16 @@ 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
-    openfn: config.formats?.openfn ?? "yaml",
-    project: config.formats?.project ?? "yaml",
-    workflow: config.formats?.workflow ?? "yaml"
-  }
-});
 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
@@ -1092,15 +1193,8 @@ var Project = class {
   meta;
   // this contains meta about the connected openfn project
   openfn;
-  // workspace-wide configuration options
-  // 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
+  workspace;
+  config;
   collections;
   static from(type, data, options = {}) {
     if (type === "state") {
@@ -1125,8 +1219,10 @@ var Project = class {
   // 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);
+  // TODO maybe the constructor is (data, Workspace)
+  constructor(data, config = {}) {
+    this.setConfig(config);
+    this.id = data.id ?? data.name ? slugify(data.name) : humanId({ separator: "-", capitalize: false });
     this.name = data.name;
     this.description = data.description;
     this.openfn = data.openfn;
@@ -1136,22 +1232,18 @@ var Project = class {
     this.credentials = data.credentials;
     this.meta = data.meta;
   }
+  setConfig(config) {
+    this.config = buildConfig(config);
+  }
   serialize(type = "json", options) {
     if (type in serialize_exports) {
       return serialize_exports[type](this, options);
     }
     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?
@@ -1186,6 +1278,10 @@ var Project = class {
 };
 var Project_default = Project;
 
+// src/Workspace.ts
+import path3 from "node:path";
+import fs3 from "node:fs";
+
 // src/util/path-exists.ts
 import fs2 from "fs";
 function pathExists(fpath, type) {
@@ -1202,57 +1298,66 @@ function pathExists(fpath, type) {
 }
 
 // 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;
+  activeProject;
   projects = [];
   projectPaths = /* @__PURE__ */ new Map();
   isValid = false;
   constructor(workspacePath) {
-    const openfnYamlPath = path2.join(workspacePath, OPENFN_YAML_FILE);
-    if (pathExists(openfnYamlPath, "file")) {
+    let context;
+    try {
+      const { type, content } = findWorkspaceFile(workspacePath);
+      context = loadWorkspaceFile(content, type);
       this.isValid = true;
-      const data = fs3.readFileSync(openfnYamlPath, "utf-8");
-      this.config = yamlToJson(data);
+    } catch (e) {
+      console.log(e);
+      return;
     }
-    const projectsPath = path2.join(
-      workspacePath,
-      this.config?.dirs?.projects ?? PROJECTS_DIRECTORY
-    );
+    this.config = buildConfig(context.workspace);
+    this.activeProject = context.project;
+    const projectsPath = path3.join(workspacePath, this.config.dirs.projects);
     if (this.isValid && pathExists(projectsPath, "directory")) {
       const stateFiles = fs3.readdirSync(projectsPath).filter(
-        (fileName) => PROJECT_EXTENSIONS.includes(path2.extname(fileName)) && path2.parse(fileName).name !== "openfn"
+        (fileName) => PROJECT_EXTENSIONS.includes(path3.extname(fileName)) && path3.parse(fileName).name !== "openfn"
       );
       this.projects = stateFiles.map((file) => {
-        const stateFilePath = path2.join(projectsPath, 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);
+        this.projectPaths.set(project.id, stateFilePath);
         return project;
       }).filter((s) => s);
     }
   }
+  // TODO
+  // This will load a project within this workspace
+  // uses Project.from
+  // Rather than doing new Workspace + Project.from(),
+  // you can do it in a single call
+  loadProject() {
+  }
   list() {
     return this.projects;
   }
+  /** 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.config?.name);
+    return this.projects.find((p) => p.id === this.activeProject?.id) ?? this.projects.find((p) => p.openfn?.uuid === this.activeProject?.id);
   }
+  // TODO this needs to return default values
+  // We should always rely on the workspace to load these values
   getConfig() {
     return this.config;
   }
   get activeProjectId() {
-    return this.config?.name;
+    return this.activeProject?.id;
   }
   get valid() {
     return this.isValid;
@@ -1261,8 +1366,8 @@ var Workspace = class {
 
 // src/gen/generator.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import path3 from "node:path";
-import { readFileSync } from "node:fs";
+import path4 from "node:path";
+import { readFileSync as readFileSync2 } from "node:fs";
 import { grammar } from "ohm-js";
 var parser;
 var initOperations = (options = {}) => {
@@ -1358,8 +1463,8 @@ var initOperations = (options = {}) => {
   return operations;
 };
 var createParser = () => {
-  const grammarPath = path3.resolve(import.meta.dirname, "workflow.ohm");
-  const contents = readFileSync(grammarPath, "utf-8");
+  const grammarPath = path4.resolve(import.meta.dirname, "workflow.ohm");
+  const contents = readFileSync2(grammarPath, "utf-8");
   const parser2 = grammar(contents);
   return {
     parse(str, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/project",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Read, serialize, replicate and sync OpenFn projects",
   "type": "module",
   "exports": {
@@ -28,11 +28,12 @@
   },
   "dependencies": {
     "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.4",
+    "@openfn/lexicon": "^1.2.5",
     "@openfn/logger": "1.0.6"
   },
   "files": [