Demo Extension API (Swift) and Extension Store

[pkasila]

Description

Demoing the Extension API and basic Extension Store

• Basic Extension Store API server is deployed on my personal server at the moment
• Basic Extension API package for Swift-based API (it just a class conforming to protocol, at the moment no APIs are implemented)
• Loading Swift extensions as Bundles
• Add alert that workspace should be reopened for extensions to start working

Someone else should work on the UI for Extension Store 😄

Related Issue

• 💬 Determine Extension Architecture #180
• ✨ Extension Store #183

Checklist

• I read and understood the contributing guide as well as the code of conduct
• My changes generate no new warnings
• My code builds and runs on my machine
• Review requested

Screenshots

As far it's just PoC, UI is not implemented according to the concept

2022-04-09.23.57.45.mov

How to work with Extensions?

First of all, right now Extension Store API adds plugin releases by receiving web-hooks from GitHub. So, you need to set up a GitHub repository. Everything in this, let's say, tutorial is based on pkasila/helloworld-extension - demo extension.

About Extension's Bundle

Any extension is a Bundle. This bundle should have ceext extension. Also, this bundle should reference CodeEditKit as its dependency.

You should declare a subclass of ExtensionBuilder which has build(withAPI:) call which returns ExtensionInterface conforming class.

import Foundation
import CodeEditKit

public class HelloWorldExtension: ExtensionInterface {
    var api: ExtensionAPI

    init(api: ExtensionAPI) {
        self.api = api
        print("Hello from HelloWorldExtension: \(api)!")
    }
}

@objc(HelloWorldBuilder)
public class HelloWorldBuilder: ExtensionBuilder {
    public override func build(withAPI api: ExtensionAPI) -> ExtensionInterface {
        return HelloWorldExtension(api: api)
    }
}

The subclass of ExtensionBuilder should be set as the NSPrincipalClass in Info.plist

Authorizing requests

In this PR, Extension Store API server is set to https://codeedit.pkasila.net/api/ (my personal server) which is secured using my Keycloak server (register, login).

NOTE: We need to deploy this Extension Store API server somewhere else.

Then you send request to receive a token to access API:

curl -XPOST -d 'client_id=codeedit-app&username=[USERNAME]&password=[PASSWORD]&grant_type=password' 'https://keycloak.pkasila.net/auth/realms/CodeEdit/protocol/openid-connect/token'

Then, you need provide this token in Authorization header:

Authorization: Bearer [TOKEN_GOES_HERE]

Publishing a plugin

You need to make a POST-request:

Authorization: Bearer ...
Content-Type: application/json

{
    "manifest": {
        "name":"helloworld",
        "displayName":"Hello World", 
        "homepage":"https://codeedit.app/", 
        "repository":"https://github.com/pkasila/codeedit-helloworld-extension", 
        "issues":"https://github.com/pkasila/codeedit-helloworld-extension"
    },
    "management":"gh_releases",
    "sdk": "swift"
}

Server will return something like this (remember, you will receive secret only once):

{
    "secret": "[YOUR_SECRET]",
    "plugin": {
        "ban":null,
        "manifest": {
            "repository":"https:\/\/github.com\/pkasila\/codeedit-helloworld-extension",
            "homepage":"https:\/\/codeedit.app\/",
            "name":"helloworld",
            "displayName":"Hello World",
            "issues":"https:\/\/github.com\/pkasila\/codeedit-helloworld-extension"
        },
        "author":"5810845E-3D12-4535-8590-5DD356173E40",
        "management":"gh_releases",
        "id":"163E6B08-3485-49B0-AC01-0626BCFCD0BC",
        "sdk":"swift"
    }
}

Then, you need to set up web-hooks on GitHub, so Extension Store API could receive information about new releases

Setting up web-hooks with GitHub Releases

Go to your repository settings and to Webhooks tab. Here you need to:

• Set URL to: https://codeedit.pkasila.net/api/webhooks/[YOUR_PLUGIN_ID: root.plugin.id]/github
• Set Content type to: application/json
• Set secret to one you received in the server response
• In "Which events would you like to trigger this webhook?" select: Let me select individual events.
• Leave Releases only in Individual events

You will have something like this:

First delivery may be unsuccessful, but when you will publish new releases everything should work fine.

Publishing releases

You publish releases to GitHub Releases as you would usually do. But you need to provide an additional asset to the release, so CodeEdit would be able to download, install and load the extension.

The final version of the extension should be archived as TAR-archive:

tar cvhf extension.tar HelloWorldExtension.ceext

Then, extension.tar should be attached to your release (the name of the file should be exactly extension.tar).

When Extension Store API will receive a web-hook, it will automatically add release to the database. If you delete release from GitHub, then it will automatically delete it from the database after a web-hook.

[nanashili]

@pkasila look at #414 the right side of the Package Manager maybe we can follow that UI?

[nanashili]

Or ultimately we can follow VS Code design and open an editor screen which shows the extensions it does give the extensions developers more space to work with.

[pkasila]

@pkasila look at #414 the right side of the Package Manager maybe we can follow that UI?

As I said this is just a PoC of Extensions Store and Extension API, so UI should be handled by someone else. And also I think it's better to discuss UI with @austincondiff.

But I think that it is a good option to have UI similar to #414.

[nanashili]

@pkasila look at #414 the right side of the Package Manager maybe we can follow that UI?

As I said this is just a PoC of Extensions Store and Extension API, so UI should be handled by someone else. And also I think it's better to discuss UI with @austincondiff.

But I think that it is a good option to have UI similar to #414.

Okay, I'll build the UI for it will just need to look into MD support but the nice thing about the Text view is it automatically supports MD

[Angelk90]

@pkasila : You could put a sample video of how everything happens, from installation to use.

[pkasila]

@Angelk90 There are no APIs for extensions implemented yet (except sample one), so video below just shows how app loads extensions on workspace opening (and extension prints "Hello from HelloWorldExtension: CodeEdit.CodeEditAPI!" on load).

codeedit_extensions_demo.mp4

[samymih]

great work, keep it up! 👍🏻

[Angelk90]

@pkasila : Some suggestions:

• In the release field, it would be possible to previously assign the latest version of the extension as a value.
• After installation, I believe that you must always restart the program if you want to try the extension.
  It would be possible instead of having that modal telling you, that the installation was successful and if you want to try, then reboot.
  Having a modal that tells you this, with a button that allows you to restart the program by yourself, close the project and reopen it.

[pkasila]

@Angelk90 On the first suggestion I'll work a little bit later (it'll require some changes on the server-side). But with the second one here we go:

2022-04-09.23.57.45.mov

[Angelk90]

@pkasila : Great, how about the loading is in the center?

Registrazione.schermo.2022-04-09.alle.23.02.48.mov

Then I think after installing it would be useful too, probably show what version is installed.

[Angelk90]

@pkasila : If the newly installed "Hello world" extension had a settings window, how can I access it?

[pkasila]

@pkasila : If the newly installed "Hello world" extension had a settings window, how can I access it?

It's a great question. Right now I can suggest 3 options:

1. (code approach) We can add static func settings() -> ... function to ExtensionBuilder class and this function should return (one of):
   1.1. a set of settings (so CodeEdit handles settings in some unified way)
   1.2. a function for window to be created
   1.3. a NSViewController with extension's settings (extension handles its settings)
2. (bundle resource approach) We can make extension developers add their settings fields to Info.plist or any other file in the extension's bundle, so CodeEdit will parse this file and handle settings in some unified way.
3. Actually we can make it work with XIBs in the extension's bundle 😄

Again, this PR is just a PoC of how we can distribute, install, load and let extension interact with CodeEdit via ExtensionAPI protocol conforming class.

[Angelk90]

@pkasila : Better to ask the problems now, than later.

[jasonplatts]

@pkasila : If the newly installed "Hello world" extension had a settings window, how can I access it?

It's a great question. Right now I can suggest 3 options:

1. (code approach) We can add static func settings() -> ... function to ExtensionBuilder class and this function should return (one of):
   1.1. a set of settings (so CodeEdit handles settings in some unified way)
   1.2. a function for window to be created
   1.3. a NSViewController with extension's settings (extension handles its settings)
2. (bundle resource approach) We can make extension developers add their settings fields to Info.plist or any other file in the extension's bundle, so CodeEdit will parse this file and handle settings in some unified way.
3. Actually we can make it work with XIBs in the extension's bundle 😄

Again, this PR is just a PoC of how we can distribute, install, load and let extension interact with CodeEdit via ExtensionAPI protocol conforming class.

Great question @Angelk90. We will need to consider that many extensions will want to store both global and project-specific settings. @austincondiff, this is something that is really confusing for users in Nova. The first white window is where global settings are shown and the second darker project window is where project-specific settings are found.

[jasonplatts]

Really nice work @pkasila! It's great progress.

[jasonplatts]

Looks great @pkasila!