programmatic interface

[travi]

i've been finding myself wanting to accomplish similar goals to what the cli package does, but in non-terminal contexts. i really like the convention of the octoherd script taking an octokit instance, a repo, and maybe some options, but the herd part of the equation is limited to being used within the cli. i'm wondering if there would be value in exposing some of the core herd functionality as a programmatic interface, possibly as a separate package.

i think the primary logic is essentially

cli/lib/run-script-against-repositories.js

Lines 54 to 69 in ecc8f5b

	for (const repository of repositories) {
	state.octokit.log.info(
	{ octoherd: true },
	"Running on %s ...",
	repository.full_name
	);
	try {
	const { id, owner, name } = repository;
	state.octokit.log.setContext({ repository: { id, owner, name } });
	await state.script(state.octokit, repository, state.userOptions);
	} catch (error) {
	if (!error.cancel) throw error;
	state.octokit.log.debug(error.message);
	}
	}

, which might be so small that it is questionable whether it is valuable to pull it out vs duplicate in other clients. in general, i lean in the direction of sharing logic, even when small, but i think that is the big discussion point we'd need to align on before the rest of this thought matters.

the resolve-repositories logic could make sense as another function to expose, but that feels still a bit specific to the cli context in its current form.

in addition to the non-terminal context, exposing the core logic that expects an octokit instance and the list of normalized repos could be a way to enable alternative ways to determine the list of repos and support alternative auth options for octokit.

if this were available, that programmatic interface could enable other contexts beyond being from from a terminal, but would also enable embedding into other cli implementations. maybe this cli package becomes more of a reference implementation and easy default, but the programmatic interface is the path for more complex implementations?

[gr2m]

I'm very open to it! I always thought of the CLI as only the first runtime for octoherd scripts. I still dream of an octoherd.dev website/app for an alternative runtime for example. So extracting a programmatic interface that then the different runtimes could use sounds great to me

[travi]

great! how do you see something like this moving forward? should this be a new repo and package, or something that is a smaller step, like exposing another function through the public interface of this existing package for now? i think i lean toward the former option of a new repo/package, but want to confirm where your thoughts are.

if a new repo/package, i normally call this sort of base logic a core package, so something like @octoherd/core makes sense to me. do you have any alternative conventions in mind for this sort of extraction? we would want to make sure that the new package was consumed by the cli shortly after being available to keep the logic shared.

[gr2m]

yes I'd keep the repository and expose another function, at least as a first step.

[travi]

thats fair. small steps are good.

in that case, would you want to expose it from the index.js so that it is another named import available from the normal @octoherd/cli export, or would you define as a separate export from the package? it could be exposed as a named import under something like @octoherd/cli/core or similar

[gr2m]

I think I'd just expose it from index.js. We can also deliberately not document it for now if we are unsure about how to expose it and what it's API should be, or expose it as experimental_SomethingSomething to make it extra clear that this is not ready for production until renamed