Hi all, we’ve been hard at work on ForgeBox 2.0 and the corresponding CommandBox CLI features that focus on your productivity in publishing packages and keeping them up to date as well as tracking all the versions of your dependencies.
For starters, the ForgeBox 2.0 isn’t published yet in production. If you download the bleeding edge of CommandBox (3.1.0) you will be pointing to our stage server. it’s a recent backup of production data, but since the new ForgeBox site is a rewrite on top of an updated data structure, it needs to be a separate database. So, feel free to use it, but remember you’re not going to be installing or publishing to the live ForgeBox site yet until we roll out this release.
Download CommandBox 3.1.0 here:
http://integration.stg.ortussolutions.com/artifacts/ortussolutions/commandbox/3.1.0/
Running “upgrade --latest” will also give you this URL.
Here’s an overview of the new stuff for you to try out:
New ForgeBox 2.0 API
The API has been rewritten as a fresh ColdBox module using ORM and a new database. You probably don’t really care since the endpoints are mostly the same, but nonetheless it all needs tested to make sure we didn’t break anything.
Track more than one version of your package at a time in ForgeBox
As part of the new data structure in the ForgeBox site, a package no longer has a single version, but as many versions as you like. Each version stores its own download URL, and box.json data. The new ForgeBox.io site will show these. For now you can see the available versions from the CLI with the “forgebox show” command:
CommandBox> forgebox show coldbox
ColdBox Platform ( Luis Majano, lmajano@gmail.com ) *****
The ColdBox MVC Platform manual can be found here: http://coldbox.ortusbooks.com/
Type: MVC
Slug: “coldbox”
Summary: The ColdBox Platform
Versions: 4.3.0-snapshot, 4.2.0, 4.1.0, 4.0.0, 4.0.0-rc, 3.8.2, 3.8.1, 3.8.0, 3.7.0
…
Create user from CLI
Also part of the new API is the ability to create a new ForgeBox user right from the CLI. Run the “forgebox register” command to get started. Feel free to test this, but if you already have a ForgeBox user, you can just skip to the next step and login. The confirmation E-mail is bypassed right now for testing. If you forget your password on our stage server, there’s not currently a way to reset your password, but there will be.
Authenticate from the CLI
Once you have a confirmed user, you can run “forgebox login” to authenticate your account. This will store your API key in a CommandBox config setting. You can see it with:
CommandBox> config show endpoints.forgebox
Bump tags Git repo
This is a nice feature that npm does. When you use the “package version” command (aliased as “bump”), if you are running the command in a Git repository and the working directory is clean, the CLI will create a tag for you that’s named after the version and commit it. You can supply a custom message if you like each time or as a global setting and even turn the entire feature off with a config setting flag.
bump --patch
bump --minor message=“Upgrading to ${version} because I want to”
config set tagVersionMessage=“My default tag message”
config set tagVersion=false
Publish packages from the CLI
This is where it really gets fun. You basically don’t ever need to touch the forgebox website again if you don’t want to! The “forgebox publish” command (aliased as “publish”) will add a new package to ForgeBox, or update an existing one (that belongs to you). If the local version number is different, a new version will be created in ForgeBox. Usually you would use the bump command above right before publishing. Remember, ForgeBox does not store your actual package files like npm. We just point to your download location. We’ve been optimizing this as much as possible to work seamlessly with a Git repo. When you publish a package, this data is sent to the server:
- Your box.json. Specifically
- Package name
- slug
- version
- type
- location (this is where to download your package from and can be an HTTP URL or ANY VALID package ID such as “repoUser/repoName#v1.2.3”)
- etc
- The contents of your readme[.txt|.md] file one of those exists
- The contents of your changelog[.txt|.md] file one of those exists
- The contents of your instructions[.txt|.md] file one of those exists
- Your API key config setting to authenticate
That’s it. Once you run this command, you can run “forgebox show my-package” to confirm it’s there.
Any updates to your readme, title, etc will overwrite the old data.
If you change the slug, a new package will be created.
If you change the version, a new version will be added to the existing package.
I’ve run a backfill on the new ForgeBox database to create a single version on every package equal to whatever the last version was saved in ForgeBox.
Semantic Versioning support
This is huge and goes hand-in-hand with the new versioning. One of the biggest complaints about ForgeBox is you couldn’t say “install foo@1.2.3” if the latest version of foo was actually 2.0.0. Well, now you can. Any version on a ForgeBox package which is typed after an @ sign for the install command or as the “value” of your dependency in box.json will now be used to look up the correct version in ForgeBox (assuming it exists) and the proper download URL will be used to download and save it in artifacts. Remember, the download URL comes from the “location” property of the box.json and can be any valid packager ID.
And that’s not all-- we now fully support the entire implementation of npm-style semver ranges. That means you tell CommandBox a “fuzzy” range of versions you’re ok with and it finds the best match. Stable versions are determined by the existence of a pre-release ID like “-alpha”. Therefore 1.2.3-rc is a pre-release but 1.2.3 is a stable build.
Here’s some examples:
Latest stable version
CommandBox> install foo
Same as above
CommandBox> install foo@stable
latest version, even if pre release (bleeding edge)
CommandBox> install foo@be
A specific version
CommandBox> install foo@1.2.3
Any version with a major number of 4 (4.1, 4.2, 4.9, etc)
CommandBox> install foo@4.x
Any version greater than 1.5.0
CommandBox> install foo@>1.5.0
Any version greater than 5.2 but less than or equal to 6.3.4
CommandBox> install “foo@>5.2 <=6.3.4”
Any version greater than or equal to 1.2 but less than or equal to 3.2
CommandBox> install “foo@1.2 - 3.2”
Allows patch-level changes if a minor version is specified. Allows minor-level changes if not. (2.1.2, 2.1.3, 2.1.4, etc)
CommandBox> install foo@~2.1
Any greater version that does not modify the left-most non-zero digit. 4.2, 4.3, 4.9, etc
CommandBox> install foo@^4.1.4
And finally, the “update” command really works now as it takes the semver range stored in your box.json into account. For example, if you have a dependency installed with a version saved of ^2.0.0 it will update you all the way to 2.9.9 but it will never install 3.0.0 until you ask it to. This is because breaking changes come in major versions, but minor releases are supposed to be compatible.
Interceptor-based CLI scripts
Moving along, we’ve borrowed another idea from npm’s run-scripts. We allow a struct in your box.json that can define named scripts comprised of CommandBox commands. We’ve hooked these scripts up to all the built-in interception points in CommandBox (and added a few new ones) so you can prescribe arbitrary commands on a package-by-package basis to run any time you bump a package version, publish to ForgeBox, start a server, or exit the CLI.
Here’s an example box.json file: