Skip to content

programmatic interface #219

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
travi opened this issue Apr 30, 2025 · 3 comments · May be fixed by #221
Open

programmatic interface #219

travi opened this issue Apr 30, 2025 · 3 comments · May be fixed by #221

Comments

@travi
Copy link
Member

travi commented Apr 30, 2025

Discussed in #218

Originally posted by travi April 29, 2025
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?
@travi
Copy link
Member Author

travi commented Apr 30, 2025

one potential complication i'm seeing as i look at extracting this is the setContext from the octokit logger.

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

Line 63 in ecc8f5b

state.octokit.log.setContext({ repository: { id, owner, name } });

this appears to be specifically added in the octoherd specific octokit. this works in the current cli context because it specifically uses that octokit. do we want to require that specific octokit be the one used when calling the programmatic interface? i admit that i don't fully have my head around the value that the setContext capability adds, but i think it could be limiting to require that because one of the primary reasons i'm seeing it as valuable to expose is that an existing octokit instance could be passed from the caller. however, the existing octokit instances from existing callers likely are not the octoherd specific instance.

what thoughts do you have about this detail?

@gr2m
Copy link
Member

gr2m commented Apr 30, 2025

i admit that i don't fully have my head around the value that the setContext capability adds

Logging for Octoherd is relevant for reports, which is not something I got to implement yet. But the idea is that Octoherd out of the box can do a structured log into a file, and then at the end run a reduce function that can present useful information. The idea I had was to support other exports beyond script, like report. And if it's present, it would be called by the runner of said script at the right time with the right information.

For logging, Octoherd's Octokit has an own internal plugin: https://github.com/octoherd/octokit/blob/1fd16014024039e79b0120ca4606f554b4a7cd04/octokit-plugins/logger.js

I think for the programmatic interface we might not need to take any of this into account. I think just using a standard @octokit/core constructor should work, but users of the programmatic interface can pass in their own customized instance of course, e.g. if they want throttling or retries.

travi added a commit to travi/octoherd-cli that referenced this issue May 1, 2025
@travi
refactor(programmatic-interface): extract logic to run script against…
0f74e59 
… a provided list of repositories

for octoherd#219
travi added a commit that referenced this issue May 1, 2025
@travi
refactor(programmatic-interface): extract logic to run script against…
d801785 
… a provided list of repositories

for #219
travi added a commit that referenced this issue May 1, 2025
@travi
refactor(programmatic-interface): extract logic to run script against…
b4fffa5 
… a provided list of repositories

for #219
@travi travi mentioned this issue May 1, 2025
Merged
@travi
Copy link
Member Author

travi commented May 1, 2025

Logging for Octoherd is relevant for reports, which is not something I got to implement yet. But the idea is that Octoherd out of the box can do a structured log into a file, and then at the end run a reduce function that can present useful information.

this sounds really useful. interested to learn more about the goal at some point

travi added a commit that referenced this issue May 5, 2025
@travi
refactor: improve naming of logic for loading repositories and runnin…
3c7fef4 
…g a script

for #219
travi added a commit to travi/octoherd-cli that referenced this issue May 5, 2025
@travi
refactor: improve naming of logic for loading repositories and runnin…
574989f 
…g a script

for octoherd#219
travi added a commit that referenced this issue May 6, 2025
@travi
fix(script): await execution of the script
f0602b9 
for #219
@travi travi linked a pull request May 27, 2025 that will close this issue
Draft
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
2 participants
@gr2m @travi