CLI: Notes with elias

[josephjclark]

1. DONE can't execute a folder - openfn execute my-dir will fail (it's trying to map my-dir to a folder). This is fine but the ~tutorial will need an update ~ but CLI help will need an update (or dir containing a job.js file)
2. DONE If you forget an adaptor openfn job.js you'll probably get an error like "failed to load sourcemap" which is wierd and scary

[josephjclark]

Probably need to rethink the tutorial - we should have one tutorial which starts with the app

[josephjclark]

In new pull, the endpoint does not seem to default to app.openfn.org. Also if the endpoint is missing or malformed, the error message is poor

[josephjclark]

The app doesn't expose credential UUIDs anywhere, which makes the local credential map harder to build

[josephjclark]

"Github sync is not enabled for your plan" on CLI push. This is a huge problem!!!! Affects all free plans?! OMG

[elias-ba]

Hey Joe, thanks again for the amazing pairing we had yesterday on the CLI and all the help and mentoring you gave me to learn. After our session I took the rest of the day to look at the code a little bit and analyze some of the issues we faced. I used Claude Code to help me review the source and do the analysis faster. Here's what I found, happy to be corrected on any of this since I'm still getting familiar with the codebase!

Error 1: openfn execute execute → cryptic ENOENT

I had a directory called execute/ with fetch_todos.js inside, and ran openfn execute execute expecting the CLI to look inside it. I think what's happening is that in options.ts (lines 404-411), the path execute doesn't match .json, .yaml, or .js, so it falls through to treating it as a workflow name. From there load-plan.ts (lines 44-50) tries to load a workspace, which hits findWorkspaceFile in config.ts (lines 96-116), and that just rethrows the raw ENOENT when it can't find openfn.yaml or openfn.json.

I would suggest replacing that rethrow in findWorkspaceFile (config.ts line 109-113) with something more descriptive:

} catch (e) {
  throw new Error(
    `No workspace configuration found at ${dir}. ` +
    `Expected openfn.yaml or openfn.json. ` +
    `If you're trying to execute a file, pass the path directly: openfn ${dir}/job.js -a <adaptor>`
  );
}

Also as you noted, the CLI help text says "or a dir containing a job.js file" which seems misleading since directory execution doesn't actually work that way.

Error 2: No adaptor → confusing sourcemap error

When I ran openfn execute/fetch_todos.js without -a http, I got the "no adaptor" warning (good!), but then this showed up before the actual ReferenceError: get is not defined:

Error occurred trying to resolve sourcemap for  job-1
Error: "job-1.js" is not in the SourceMap.

I think what's happening is that without an adaptor, the compiler produces a sourceMap that doesn't contain the expected file entries. Then in sourcemap-errors.ts (line 31), smc.sourceContentFor(fileName) fails because "job-1.js" isn't in the sourceMap, and the catch block on lines 38-42 does a raw console.warn() instead of going through the logger.

I think a possible fix would be to use the returnNullOnMissing parameter that sourceContentFor already supports:

if (error.pos && !isNaN(error.pos.line!)) {
  const fileName = `${job.name || job.id || 'src'}.js`;
  const content = smc.sourceContentFor(fileName, true); // true = return null on missing
  if (content) {
    const src = content.split('\n');
    const line = src[error.pos.line! - 1];
    error.pos.src = line;
  }
}

This would suppress the misleading sourcemap error entirely. Alternatively, the console.warn on lines 38-42 could use the logger instead of raw console.warn so it respects the --log level setting.

I went ahead and opened a small PR for this: #1250.

Error 3: Missing OPENFN_ENDPOINT → TypeError: Invalid URL

I created a .env with only OPENFN_API_KEY and ran openfn project pull <uuid>. Got TypeError: Invalid URL with input: '/api/provision/...'. I think this is because in loadAppAuthConfig (projects/util.ts lines 14-38), when OPENFN_ENDPOINT is missing, config.endpoint stays undefined, and then getLightningUrl (line 98) does new URL('/api/provision/...', undefined) which throws. I noticed there's already a TODO on line 35: // TODO probably need to throw — so it looks like this was anticipated!

I would suggest adding validation for the API key in loadAppAuthConfig, and for the endpoint in getLightningUrl (since the endpoint can also come from the local project file, validating it too early in loadAppAuthConfig would break that flow):

// In loadAppAuthConfig:
if (!config.apiKey) {
  throw new CLIError(
    'OPENFN_API_KEY is required. Set it in .env, pass --api-key, or set the environment variable.'
  );
}

// In getLightningUrl:
if (!endpoint) {
  throw new CLIError(
    'OPENFN_ENDPOINT is required. Set it in .env, pass --endpoint, or set the environment variable.\n' +
    'Example: OPENFN_ENDPOINT=https://app.openfn.org'
  );
}

I went ahead and opened a small PR for this: #1251.

Error 4: Deploy 403 → "Github Sync is not enabled for your plan"

When I ran openfn project deploy, I got:

[CLI] ✘ Failed to deploy project:
[CLI] ✘ { "error": "Github Sync is not enabled for your plan." }
[CLI] ✘ Failed to deploy project elias-sandbox: 403

I think there are two things going on here. On the CLI side, in deployProject (projects/util.ts lines 160-167), the 403 body is parsed and logged, but then a generic CLIError is thrown with just the status code, so the user sees the error twice in slightly different forms. I think this could be tightened up by combining them into a single error and removing the separate logger?.error() on lines 163-164:

const errorMsg = body?.error || `HTTP ${response.status}`;
throw new CLIError(
  `Failed to deploy project ${state.name}: ${errorMsg}`
);

On the Lightning side, the "Github Sync is not enabled" message comes from the provisioning API reusing the same permission check as GitHub sync, which is confusing for CLI users who have no idea what GitHub sync has to do with anything. I opened a PR to fix this: OpenFn/lightning#4427, it uses a distinct api_provisioning action type in the provisioner so the error message can say "Project provisioning via API is not enabled for your plan" instead.

[elias-ba]

Hey @josephjclark, I went ahead and opened tiny PRs for errors 2, 3, and 4:

• Error 2 (sourcemap): Handle missing source in sourcemap gracefully #1250
• Error 3 (missing endpoint): Validate API key and endpoint before making requests #1251
• Error 4 (Github Sync message): Use distinct action type for API provisioning error message lightning#4427

The only one that may need your decision is Error 1, I didn't touch it since it feels more like a design question around how the CLI should handle directory paths vs workflow names, and I wasn't sure what the intended behavior should be there.

[josephjclark]

From frank: do not write the cli key to the project.yaml file