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:

 

Running "upgrade --latest" will also give you this URL.

 

Here's an overview of the new stuff for you to try out:

 

 

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.

 

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, [email protected] ) *****

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

...

 

 

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.  

 

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.

 

CommandBox> bump --patch
CommandBox> bump --minor message="Upgrading to ${Setting: version not found} because I want to"
CommandBox> config set tagVersionMessage="My default tag message"
CommandBox> config set tagVersion=false

 

 

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

 

 

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 [email protected]" 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 [email protected]

# Any version with a major number of 4 (4.1, 4.2, 4.9, etc)
CommandBox> install [email protected]

# 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 "[email protected] - 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 install3.0.0 until you ask it to.  This is because breaking changes come in major versions, but minor releases are supposed to be compatible.

 

 

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:

 

{
  "name" : "My Package",
  "slug" : "my-package",
  "version" : "1.0.0",
  "scripts" : {
   "postVersion" : "package set location='gitUser/gitRepo#`package version`'"
   "postPublish" : "!git push"
  }
}

Any time I bump a package version, I'll update the location property to have the latest version for the Git tag.

And when I publish my package in ForgeBox, I'll automatically push my changes to Github (assuming I have a Git client installed at the command line)

 

This is a small one, but the new "system-log" command outputs the path to the CommandBox log file. You can use it creatively by piping its output into other commands:

 

CommandBox> system-log | open
CommandBox> system-log | cat
CommandBox> system-log | tail

 

 

There's a number of small things we've fixed here and there that you can see in JIRA.

 

 

We are also working hard on the ability for you to not only start up Lucee 4.5 servers but also:

• Adobe CF 
• Lucee 5.0
• Railo 4.2
• Any random WAR you want 

This will be part of the 3.1.0 release and I'll post here again when it's ready to try out on the bleeding edge.

 

 

# Create user (first time only)
CommandBox> forgebox register username password [email protected] firstName lastName
CommandBox> forgebox login username password

# Create package/git repo
CommandBox> mkdir mypackage --cd
CommandBox> !git init
CommandBox> package init slug=my-package type=modules location=gitUser/my-package
CommandBox> bump --minor message="Initial Commit"

# Publish it
CommandBox> !git remote add origin <git url>
CommandBox> !git push
CommandBox> publish

# Viewable and installable by the world!
CommandBox> forgebox show my-package
CommandBox> install my-package