varabyte / kobweb-cli

The CLI binary that drives the interactive Kobweb experience. See varabyte/kobweb

This project is the CLI binary for the Kobweb framework.

Background

Kobweb is a Kotlin framework for building reactive web applications. You can view the project here: (https://github.com/varabyte/kobweb)

The code in here used to be part of the main Kobweb codebase, but it made sense to split it out into its own project for a couple of reasons:

• It has its own release cadence completely separate from the Kobweb libraries.
• It is updated far less often than Kobweb is.
• In GitHub, it was very hard to do a diff between two CLI releases, since one had to read past all the library commits that were there.
• It is common while working on Kobweb to clean and rebuild all library artifacts, but doing so often deletes the CLI at the same time.
• Most of the dependencies used by the CLI are completely different to those used by Kobweb, making the libs.versions.toml file feel a bit crowded.

This binary does depend on one of the Kobweb artifacts, a library called kobweb-common, and in the early days of Kobweb was development, it required frequent updating. More recently, though, this isn't the case anymore, reducing the friction of pulling this project out into its own repository.

If we ever need to make a change to kobweb-common again for code used by this project, we can just upload an artifact snapshot and have this binary depend on it. This is a bit of a pain, but it's not a big deal.

Building

Dev

For local development...

• Check your libs.versions.toml file.

  • kobweb-cli should have a version with a -SNAPSHOT suffix.

• Install the binary: ./gradlew :kobweb:installShadowDist

  • This will create kobweb/build/install/kobweb/bin/kobweb.
  • You are encouraged to create a symlink to it which lives in your path, so you can run the kobweb command from anywhere.

Prod

For a release...

• Check your libs.versions.toml file.

  • kobweb-cli should have a version that does NOT end with a -SNAPSHOT suffix.

• Assemble the tar and zip files: ./gradlew :kobweb:assembleShadowDist

  • Files live under kobweb/build/distributions.

Important

The Kobweb CLI project has a build workflow which generates CLI artifacts every time a new commit is pushed.

You can find these by clicking on the relevant build run and then downloading the kobweb-cli-artifacts zip from the Artifacts section).

You should consider using these instead of ones you built yourself, as the CI environment is guaranteed to be pure, whereas local environments may be contaminated by things you've installed or set up on your own system.

Releasing

• Create a new release on GitHub.
• Choose a tag: "vX.Y.Z", then "Create a new tag on publish"
• Set that tag for the release title as well
• Fill out the release, using previous releases as guidance (and comparing changes to main since last time to see what's new)
• Add the .zip and .tar files downloaded from GitHub actions or, if built manually, from kobweb/build/distributions
• Confirm the release.

Publishing

Important

To successfully publish the CLI, the version must NOT be set to a SNAPSHOT version.

Caution

Be very careful with this step. If you publish things from the wrong branch, you could make a mess that could take a while to clean up.

• From https://github.com/varabyte/kobweb-cli/actions choose the "Publish" workflow.
• Be sure to select the correct target (should be a branch or tag targeting the version you just released).
• Uncheck the "Dry run" checkbox. (Although you may want to do a dry run first to make sure everything is set up correctly.)
• Run the workflow.

Manual publishing

• Set the Gradle property kobweb.cli.jreleaser.dryrun to false.
• Run ./gradlew :kobweb:jreleaserPublish

Although to do successfully publish, you must have defined the following secrets on your machine:

• varabyte.github.username
• varabyte.github.token
• sdkman.key

and the github user specified must have access to edit the varabyte organization, as the publish process modifies other sibling repositories as a side effect.

Inform users about the release

• Update the badge version at the top of the main Kobweb README
• Update the version file: https://github.com/varabyte/data/blob/main/kobweb/cli-version.txt
• Create an announcement in all relevant Kobweb communities (Discord, Slack, etc.)

kobweb-cli's Issues

Better experience for user who runs "kobweb run" in the wrong folder.

A user ran kobweb run in the root of their new Kobweb project and got the error "This is not a Kobweb application module"

What the user needed to do was do: cd site; kobweb run (or kobweb run -p site) but they didn't realize that.

It would be nice to inform the user of their mistake more clearly than a generic error. Maybe something like.

This is not a Kobweb application module.

A Kobweb application module was found in the site/ subfolder. Consider navigating in there and running kobweb run again.

Note that...

1. A project might have their kobweb application under a differently named subfolder.
2. A project might have multiple kobweb applications in their project.

So on one end, we can just look for "site/.kobweb" and report if that is found, since that's 99.99% of all cases. Or we can do something more general and walk their directory structure, maybe max 1 or 2 levels deep, looking for .kobweb folders.

Then:

This is not a Kobweb application module.

A Kobweb application module was found in the app/ subfolder. Consider navigating in there and running kobweb run again.

or

This is not a Kobweb application module.

Kobweb application modules were found in the following folders:

• site/free
• site/paid

Consider navigating into one of them and running kobweb run again.

Stop using reflection in `kobweb conf`

kobweb conf uses reflection to get the property values, which means it doesn't support new values added after the cli release. It should probably just look at the parsed yaml map

Update `kobweb create` to use the boolean [Yes] No "widget" instead of typing yes/no

This new approach was added to kobweb run, so we should update kobweb create to be consistent (if possible).

We might also want to color the default choice something different?

Allow having an informative message appear after the question but before the prompt

Currently, creating the app/empty template looks like this:

! 🪡 To learn more: https://github.com/varabyte/kobweb#silk
? Would you like to use Silk, Kobweb's powerful UI layer built on top of Compose for Web?
> yes

! 🌐 To learn more: https://github.com/varabyte/kobweb#server
? Would you like to include support for defining server behavior via API routes and API streams?
> no

This would probably look better as:

? Would you like to use Silk, Kobweb's powerful UI layer built on top of Compose for Web?
! 🪡 To learn more: https://github.com/varabyte/kobweb#silk
> yes

? Would you like to include support for defining server behavior via API routes and API streams?
! 🌐 To learn more: https://github.com/varabyte/kobweb#server
> no

But to do this, we'd need to add an "inform" parameter to the CLI's "QueryVar" command.

(Then we'd probably need to wait a few months for people to update before making the change to the empty template to use the new way, because we don't want to break users who haven't upgraded yet)

Add a command for upgrading a project's kobweb version

Maybe kobweb upgrade (which would automatically query GitHub for the latest version) or kobweb upgrade 1.2.3 if you wanted to specify it explicitly.

When run, this would find your project's gradle/libs.version.toml file and automatically update the versions of Kobweb and Compose.

If the user doesn't have a gradle/libs.version.toml file, or if they have one but it's missing kobweb, we could report a warning that we were not able to upgrade.

Note: This might be a dangerous command. Upgrading Compose is a delicate operation -- lots of other things may depend on it. So we probably have to review some concrete use-cases here to make sure the command would feel right for them - it might suck in larger projects to upgrade stuff without realizing we just broke a bunch of other dependencies.

However, it would be pretty useful for new users who just want to keep their kobweb version up to date. And it would be nice for me to send out a message every time a new version comes out to ask users to just run kobweb upgrade

Kobweb binary throws an exception instead of a useful error message if a conf.yaml file is not present

At least with kobweb run, but other commands should be checked.

To repro:

$ kobweb create app
$ cd app/site
$ rm .kobweb/conf.yaml
$ kobweb run

Allow querying a negative condition

Currently in the empty template we're jumping through a lot of hoops because we can't query a negative:

 - !<Move>
    condition: "${useWorker}"
    from: "worker/src/worker/*"
    to: "worker/src/jsMain/kotlin/${packagePath}/worker"
    description: "Rearranging worker source to conform to the user's package"
  - !<Move>
    condition: "${useWorker}"
    from: "worker/*"
    to: "donotdeleteworker"
    description: "Moving worker files to a safe location before cleanup"
  - !<Delete>
    files: "worker/*"
    description: "Removing unused worker files (if any)"
  - !<Move>
    condition: "${useWorker}"
    from: "donotdeleteworker/*"
    to: "worker"
    description: "Finalizing worker files"

This should just be:

 - !<Move>
    condition: "${useWorker}"
    from: "worker/src/worker/*"
    to: "worker/src/jsMain/kotlin/${packagePath}/worker"
    description: "Rearranging worker source to conform to the user's package"
  - !<Delete>
    condition: "${!useWorker}"
    files: "worker/*"
    description: "Removing unused worker files (if any)"

but I remember earlier when trying to get that to work, it was failing.

Use the Gradle tooling API 8.6 Problems API for reporting errors and warnings.

See also: https://docs.gradle.org/current/javadoc/org/gradle/api/problems/Problems.html

Bug: unescaped special characters in visible project name cause `kobweb run` to config error

It's not that critical, but I wanted to report it.

---

While setting up the project with kobweb create, it allows to pass any kind of character to the visible name of the project:

$ kobweb create app/empty
...
? What is the user-visible display title for your project?
> Foo's "Bar\Baz"
...

However, the config is stored in YAML, and it does not allow unescaped quotes and backslashes, leading to a config error when running the app via kobweb run:

$ kobweb run -p foobar/site
✗ A .kobweb folder's `conf.yaml` file seems to have been deleted at some point. This is not expected and Kobweb cannot run without it. Consider restoring your `conf.yaml` file from source control history if possible, or create a new, temporary Kobweb project from scratch and copy its `conf.yaml` file over, modifying it as necessary.

(BTW, the message confused me the first time, and I thought it was a problem with my Linux distribution, but it's not)

---

So, what causes such issue?

Currently, the code that checks config validity, is just a null check on config content:

kobweb-cli/kobweb/src/main/kotlin/com/varabyte/kobweb/cli/common/KobwebUtils.kt

Lines 52 to 55 in 0f68aec

	fun assertKobwebConfIn(kobwebFolder: KobwebFolder): KobwebConf {
	return KobwebConfFile(kobwebFolder).content
	?: throw KobwebException("A .kobweb folder's `conf.yaml` file seems to have been deleted at some point. This is not expected and Kobweb cannot run without it. Consider restoring your `conf.yaml` file from source control history if possible, or create a new, temporary Kobweb project from scratch and copy its `conf.yaml` file over, modifying it as necessary.")
	}

Which was always null on any parse error. I did a quick check, and it seems to lead to a non-strict YAML parser (not really sure):

https://github.com/varabyte/kobweb/blob/17e25243da037a2c3373cca33969ea97175974a4/common/kobweb-common/src/main/kotlin/com/varabyte/kobweb/project/conf/KobwebConf.kt#L233-L237

A possible solution would be to automatically escape all special symbols and show the user a small warning so they don't try it next time.

Docker build issue - No terminals could successfully be created

I have just updated to kobweb-cli 0.9.15 from 0.9.13. The new version works as expected locally but fails when being built with docker.

Exception in thread "main" java.lang.IllegalStateException: No terminals could successfully be created. Encountered exceptions:
{java.lang.IllegalStateException: Unable to create a system terminal

The docker file is taken from this article https://bitspittle.dev/blog/2023/cloud-deploy but with the cli version updated, and I am doing a static export but it doesn't get that far so don't think that matters.

Great project btw

Epic bug: Please support my favorite package manager!

In order to avoid everyone creating one off bugs for the same package manager, this bug will act as a home to collect all such requests received so far. (Of course, once someone starts working on adding support for one of them, that could be a good time to create an individual bug).

Here is the current list of package managers we are considering (but not actively working on):

• apt
• chocolatey
• flatpak
• gofish
• macports
• rpm
• snapcraft
• spec
• winget

---

NOTE: Some of these package managers may never get supported, as I'm not sure how many people actually want to use them, and supporting more releases results in more work on our end.

So even if you see your package manager on this list, it still may be worth leaving a comment below like "Yes, I want that one please! I use it particularly because..."

If you see a comment below from someone expressing support for a package manager that you also want, please give their comment a thumbs up so we can better roughly understand what people are using.

Add support for winget