Support workflow aliases via folder names

[midigofrank]

Short Description

Workflows can now be given a short local alias by renaming their folder in the workspace, so workflows/my-really-long-workflow-name → workflows/wf lets you run openfn wf.

Fixes #1292

Implementation Details

The alias is just the folder name, as suggested in the issue, so there's no extra metadata to track.

• @openfn/project
  • from-fs: if a workflow's folder name differs from its id, it's set as Workflow.alias. The alias lives on the Workflow instance only, so it never ends up in the workflow yaml, the state file, or a deploy.
  • to-fs: aliased workflows are written to workflows/<alias>/ instead of workflows/<id>/.
  • Project.getWorkflow also matches on alias, so openfn <alias>, project version <alias> etc. work.
  • An alias that clashes with another workflow's id or alias is dropped with a warning, since both would share a folder.
  • Workspace.getCheckedOutProject now passes its logger to the fs parser so that warning is visible. Side effect: existing parser messages (e.g. "Error loading expression from …") that were previously silent now show up.
• @openfn/cli
  • checkout (and therefore pull and clean) copies aliases from the checked-out project to the incoming one, matched by workflow id, so renamed folders aren't deleted. An alias that clashes with an incoming workflow's id is dropped with a warning.
  • When running a workflow, the cache path now points at the workflow's real folder.
  • README documents aliases.

Known limitation: aliases are matched by workflow id. Renaming a workflow in the app changes its id, so the next pull writes it back to a folder named after the new id and the alias has to be set again. Matching by UUID would fix this, but pull overwrites the state file before checkout runs, so the old id → UUID mapping is gone by then. Storing a UUID → alias map in openfn.yaml would also work, but it needs an openfn project alias command to record it reliably. Both felt like more than this PR needed and can follow later if renames turn out to be common.

QA Notes

Tested end to end against a local Lightning:

1. Pull a project, then rename a workflow folder: mv workflows/<id> workflows/wf
2. openfn wf runs the workflow; openfn project version wf resolves it
3. openfn project pull keeps workflows/wf and doesn't recreate workflows/<id>
4. Edit a step inside workflows/wf, then openfn project deploy. The diff only contains the edit and no alias reaches Lightning
5. Rename the workflow in Lightning (or change its name and deploy), then pull. The workflow moves to a folder named after the new id (the known limitation above)
6. Clash: give a workflow an alias equal to another workflow's id. You get a warning and the workflow goes back to its id folder

AI Usage

Please disclose whether you've used AI anywhere in this PR (it's cool, we just
want to know!):

• I have used Claude Code
• I have used another model
• I have not used AI

You can read more details in our
Responsible AI Policy

[midigofrank]

Hey @josephjclark, I've picked something up while doing a review:

An alias is the workflow's folder name, and Project.getWorkflow now matches on alias as well as id, name and UUID. That's what makes openfn <alias> and openfn project version <alias> work. But getWorkflow is also used internally for matching by id: project diff, merge, and the divergence check in checkout. Two edge cases come out of that:

1. A new remote workflow whose id equals a local alias gets matched to the wrong workflow. Say I've aliased a workflow foo, and someone creates a workflow named "foo" in the app. When the diff looks up foo locally, it finds my aliased workflow, so it reports "changed" instead of "added". Merges have the same problem.
2. Checkout copies aliases through getWorkflow too. So in theory an alias could move between two workflows that only share a name. Names normally don't look like ids, so this is unlikely, but it's the same root cause.

The fix claude is suggesting is to keep getWorkflow matching id, name and UUID only, and resolve aliases just where the user types a workflow name (running a workflow and project version). Checkout would copy aliases by exact id.

[josephjclark]

Well if there are multiple matches for a workflow we need to throw an error. Just like we do with Workspace.getProject.

I'm also up for a fuzzy findWorkflow API (throws on ambiguous) and an id-only getWorkflow. Might be worth looking at what that refactor looks like.