feat: help command

[gentlementlegen]

Resolves ubiquity-os/plugins-wishlist#17

QA run: Meniole/ubiquity-os-kernel#1 (comment)

[whilefoo]

Looks good but I worry how this will work in practice because partners won't set description and example.
I imagine in the future we would have to query each plugin - this can be part of the SDK which setups an endpoint to return name, description and usage

[rndquu]

Looks good but I worry how this will work in practice because partners won't set description and example. I imagine in the future we would have to query each plugin - this can be part of the SDK which setups an endpoint to return name, description and usage

It could also be a simple help.yml file set in a partner's plugin repository which is easier to query compared to an API endpoint. Or perhaps there's a way to set name, description and example directly in the action.yml file (not sure if custom attributes break the github action).

[gentlementlegen]

@whilefoo Agreed. Plus, if plugins handled their own help output, we could get more in depth details about a specific command. Also as @0x4007 mentioned it's not so nice to have commands that are merged together (related issue: #58)

@rndquu a file is a great idea, endpoints would work great only for Workers. Maybe we should add something to parse it and make sure it's required and valid, maybe an Action checking for its content on push or something similar to ensure its validity.

[0x4007]

(not sure if custom attributes break the github action).

https://www.perplexity.ai/search/github-actions-adding-eSszNo2lRG2n2SnPBvHeuw :

Adding extra properties in a GitHub Actions YAML file is generally acceptable as long as they do not interfere with the predefined syntax and structure required by GitHub Actions. Here are some key points to consider:

Metadata File for Actions

• Required Properties: The metadata file for GitHub Actions, named action.yml or action.yaml, must include certain required properties such as name and description[1].
• Optional Properties: There are several optional properties like author, inputs, outputs, and runs that you can include to define the behavior and configuration of your action[1].

Workflow File

• YAML Syntax: Workflow files also use YAML syntax and must be stored in the .github/workflows directory of your repository[6].
• Events and Jobs: You can define events that trigger the workflow and specify jobs that the workflow will run. Each job can have multiple steps, and you can include additional properties as needed[6].

Adding Extra Properties

• Custom Properties: You can add custom properties to your YAML files, but they should not conflict with the reserved keywords used by GitHub Actions. Custom properties can be useful for documentation or for use within your scripts.
• Environment Variables: If you need to add environment variables, you can do so using the env keyword within your workflow or action file. This is a common practice and does not break the workflow[1][2].

Example

Here is an example of a GitHub Actions workflow file with extra custom properties:

name: CI Workflow

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      CUSTOM_VAR: "custom_value"
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Custom Step
        run: echo "This is a custom step with a custom property"
        custom-property: "custom_value"

In this example, custom-property is an extra property added to a step. While this does not break the workflow, it is not a recognized property by GitHub Actions and will be ignored by the runner. However, it can be useful for documentation or for use within your scripts.

Conclusion

Adding extra properties in your GitHub Actions YAML file is generally safe as long as they do not conflict with the reserved keywords and structure required by GitHub Actions. These extra properties can be useful for documentation or custom logic within your scripts.

For more detailed information, you can refer to the official GitHub documentation on metadata syntax for GitHub Actions and workflow syntax for GitHub Actions.

Citations:
[1] https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions
[2] https://stackoverflow.com/questions/74862948/is-there-any-way-that-i-can-add-all-the-properties-to-the-github-env
[3] actions/starter-workflows#245
[4] https://github.com/marketplace/actions/properties-file-action
[5] https://github.com/orgs/community/discussions/25234
[6] https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
[7] https://github.com/google-github-actions/release-please-action
[8] https://stackoverflow.com/questions/76834581/how-to-break-line-in-github-actions-yaml-file-correctly
[9] https://www.reddit.com/r/github/comments/o8mxgg/github_actions_is_it_possible_to_break_out_a/
[10] actions/upload-artifact#472
[11] https://stackoverflow.com/questions/65242830/in-a-github-actions-workflow-is-there-a-way-to-have-multiple-jobs-reuse-the-sam
[12] https://docs.sonarsource.com/sonarcloud/advanced-setup/ci-based-analysis/github-actions-for-sonarcloud/
[13] https://github.com/actions/upload-artifact

[gentlementlegen]

Added basic command / description with the same content as we currently display for these commands in the configuration in this commit.

[0x4007]

Added basic command / description with the same content as we currently display for these commands in the configuration in this commit.

#     - name: "Query user"
#       description: "Returns the user's wallet, access, and multiplier information."
      command: "/query"
#      example: "/query @user"
      uses:

So will these eventually be relocated and hosted by the plugin itself? Why not just read some type of manifest.json, just like how Google Chrome extensions do it? @gentlementlegen

[gentlementlegen]

@0x4007 That can be an option indeed. It could be a manifest, a yaml, or any format that we can read and parse easily.

The main thing is to make it accessible easily to the kernel for both Actions and Workers. Because workers can easily provide an endpoint distributing that content, and Actions can directly point to the file.

[0x4007]

I think that it should be exposed at https://my-plugin.pages.dev/manifest.json etc.

[rndquu]

I think that it should be exposed at https://my-plugin.pages.dev/manifest.json etc.

It seems to be an overkill for plugins that work only as github actions to maintain a separate endpoint for a single file. It's easier to put manifest.json directly in the plugin github repository.

[gentlementlegen]

@0x4007 Absolutely, but Action plugins do not expose such endpoint. It's fine as long as Actions never implement any command, which most likely should not happen since commands need to be reactive and will most likely use a worker.

@rndquu yes but for Workers the Kernel is not aware of what repo it is located in, only the endpoint itself. It's okay since the same file can be exposed through the endpoint, or available through the Action.

---

In my mind it was:

• If plugin is an Action, the kernel can pick it up inside the repository directly by reading its content through octokit;
• If the plugin is a Worker, expect the manifest.json to be served through /manifest.json

Same file would be used in both cases.

[0x4007]

It's fine as long as Actions never implement any command

We should definitely not assume this. Besides I wrote specifications in the past that rely on commands and complex capabilities which require longer runtimes (i.e. LLM related.)