Octoherd integration

[lyqht]

Description

Found out from @gr2m about the Octoherd project — i believe it can be a really cool feature to have at Octokit-lite to have an integration for Octoherd scripts.

• From what I understand, Octoherd are custom scripts that can be ran for multiple repositories.
• Following their README example, you can create a customized script that does multiple things for multiple repositories at once.
• This is pretty similar to Octokit-lite's goal to help users perform GitHub operations across multiple repos efficiently as well.

Suggested solution for integrating Octoherd

Frontend

• [ ] It is important for the issue (#12) to be done before this epic.
• [ ] Add a homepage button for user to go to Octoherd page
• [ ] Add Octoherd Index Page
  • [ ] User can select repositories
  • Create a repository picker like Unfork/TopicSpace that shows repos based on forked/created by user.
  • The dropdown does not need to show the 2nd column of last push date/topics, but alternative proposals are possible.
  • [ ] User can select 1 Octoherd script to be applied to their selected repos
  • [ ] Create new input for keying in additional script arguments for selected script
  • [ ] Create an option picker like TopicSpace, but for showing all the Octoherd scripts available.
    • With #12 done, user can hover on the option and see the repo's description to roughly know what the octoherd script can do
  • [ ] Action button that shows confirmation popup and calls the new API route to perform the selected Octoherd script on selected repos after confirming
• [ ] Add Octoherd history page
  • [ ] show the transactions that user has made with Octoherd

Backend

• [ ] #21
• [ ] #24
  • Option 1. use existing updated records table & modify it to contain details that fit what is important to know from Octoherd API transactions
  • ✔ Preferred Option 2. create new table e.g. "OctoherdScriptsRan" with schema that stores the name of the Octoherd script they ran, the link to that Octoherd script and the date that they ran the Octoherd script
• [ ] #41

Docs

• [ ] Add to README under "Additional Resources" that Octoherd is available as a CLI version of this app

To work on this epic

All changes should be merged into the branch feature/octoherd, only when everything is done then the branch can be merged into the main branch.

[gr2m]

• [ ] Create an API route that does Octoherd related functions based on the custom script (may need @gr2m's advice on how to perform npx/ Octoherd commands in the backend)

Most scripts should be able to run in the browser, they are built that way. So no need to run npx, the idea is that you just import the script directly and run it, e.g. https://www.skypack.dev/view/@octoherd/script-rename-master-branch-to-main

the script modules export the script function which need to be run against a repository that your app can retrieve beforehand. Our idea is that scripts can also export other things such as inputs to describe script arguments, that way your app could show inputs to pass required and optional parameters to the scripts.

You can either send the requests directly from browser to GitHub's API or proxy them through your app. But I think the former is safer, because you'd never need to handle user access tokens in the backend

Does that make sense?

[lyqht]

the script modules export the script function which need to be run against a repository that your app can retrieve beforehand. Our idea is that scripts can also export other things such as inputs to describe script arguments, that way your app could show inputs to pass required and optional parameters to the scripts.

• Hmm do you know of any libraries that can import these scripts dynamically and run them only if the user select that particular script? Because I would imagine most scripts are imported at the top of the file, but in this case, we would have to import the selected Octoherd script only upon receiving a request from the app that the user wants to run that particular script for the repos he selected.
• Added a task above for creating 1 user input component for required parameters and 1 for optional parameters

---

You can either send the requests directly from browser to GitHub's API or proxy them through your app. But I think the former is safer, because you'd never need to handle user access tokens in the backend

Sorry, I don't quite understand what you mean by this point perhaps due to my lack of web dev knowledge. Do you mean creating the OctokitJS instance at the frontend browser is safer than how I'm creating the OctokitJS instance at the API route? I thought usually making authenticated calls is safer at the backend than the frontend.

[Lofty-Brambles]

You can either send the requests directly from browser to GitHub's API or proxy them through your app. But I think the former is safer, because you'd never need to handle user access tokens in the backend

Does that make sense?

Don't quote me on this, but I'm not sure if we do need a backend. If we have further plans to work with some user data, display logs or so, it might be necessary to call from the backend.

[lyqht]

Hello @Lofty-Brambles , I meant that the API routes are the backend here. In Next.js, the API routes are created and deployed as a combined Node.js serverless function. So in a way it is a 'backend', where users at the browser can't see any env values like SUPABASE_SERVICE_ROLE_KEY or know what's happening there.

[gr2m]

Do you mean creating the OctokitJS instance at the frontend browser is safer than how I'm creating the OctokitJS instance at the API route

I wouldn't say it's safer in every case. I'd say go whatever path works for you right now. Make it work, then make it great, and let the community help

• import these scripts dynamically

that is a built-in web feature now, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import

For example, the script at https://github.com/octoherd/script-hello-world is published to npm as https://www.npmjs.com/package/@octoherd/script-hello-world. You cannot import the module directly from npm yet, but you can use skypack, which wraps the npm registry and works great for that use case: https://www.skypack.dev/view/@octoherd/script-hello-world

You can import that script statically like you'd traditionally do with <script src="..."> tags. But you can also import the module dynamically with JavaScript when you need it. Like this

const { script } = await import('https://cdn.skypack.dev/@octoherd/script-hello-world');
console.log(script)

You can paste the above code in your developer tools console on a website like https://example.com/ which does not restrict imports from 3rd party domains (there are headers you can use to limit these, like github.com does it)

Does that make sense?

[lyqht]

Okie got it! Thanks for the explanation @gr2m, now i have a better understanding of how to import and use the script 🙏

[lyqht]

Hello @gr2m, while working on #42, I have tried to create an Octoherd-script using npm init octoherd-script and tried to import it via Skypack, I have encountered a TS problem where module is not found.

I did a workaround of by setting let script: any and exporting it, but would you have an idea if there's a better way to get the type declared in the script.js itself since there's already jsdocs there?

/**
 * Remove labels from all issues of given repositories
 *
 * @param {import('@octoherd/cli').Octokit} octokit
 * @param {import('@octoherd/cli').Repository} repository
 * @param { {labels: string} } options Custom user options passed to the CLI
 */
export async function script(octokit, repository, options) {...}

[gr2m]

Hm I'm not sure if that's possible. Skypack sends a x-typescript-types header when you add a ?dts to the import URL, but it doesn't seem to generate a .dts file from JS Doc comments.

For example https://cdn.skypack.dev/@octoherd/script-hello-world?dts sends

"x-typescript-types": "/-/@octoherd/script-hello-world@v2.0.0-DEZGCdMf3RuxtK8dUjS9/dist=es2019,mode=types/index.d.ts"

But https://cdn.skypack.dev/-/@octoherd/script-hello-world@v2.0.0-DEZGCdMf3RuxtK8dUjS9/dist=es2019,mode=types/index.d.ts only states there is no type definition file.

I think turning the JS Doc comments into types automagically is something that VS Code does, but only for locally imported modules. I'm not sure how things work when you import them from a URL.

[lyqht]

I see, then is it possible that in the octoherd-script that I've created, I change all the files there to .ts files instead so that I can get types on Octokit-lite? Would it still be compatible with octoherd? (I'm not sure how it all works under the hood 😅)

[gr2m]

I fear that won't work. I don't think that skypack compiles from TS to JS/DTS on-the-fly. You could probably add an index.d.ts file manually to the package

But why exactly do you need the types?

[lyqht]

@gr2m I was thinking that the type safety will be good if I try to write code that calls the external skypark script 😁 but I guess for now its not that important yet.