dojo / cli

:rocket: Dojo - command line tooling.

dojo

This is the foundation package for the Dojo 1 Toolkit. While still being maintained, new development is primarily focused on modern Dojo.

Checkout the Dojo framework website or if you want a more detailed technical status and overview, checkout the Dojo roadmap.

This package is sometimes referred to as the “core”, it contains the most generally applicable sub-packages and modules. The dojo package covers a wide range of functionality like Ajax, DOM manipulation, class-type programming, events, promises, data stores, drag-and-drop and internationalization libraries.

Installing

Installation instructions are available at dojotoolkit.org/download.

Getting Started

If you are starting out with Dojo, the following resources are available to you:

• Tutorials

• Reference Guide

• API Documentation

• Community Forum

What to Use Dojo For and When to Use It

The following is a brief sampling of some of the areas where Dojo may prove to be the right tool for your next project:

• For keeping your code fast and maintainable, Dojo offers an asynchronous module definition (AMD) loader -- encapsulating pieces of code into useful units, loading small JavaScript files only when they are needed, and loading files separately even when they are dependent on one another.

• When you want to easily extend existing classes, share functionality among a number of classes, and maximize code reuse, Dojo provides class-like inheritance and “mixins.”

• For creating advanced and customizable user interfaces out of refined, efficient, and modular pieces, Dojo’s Dijit framework offers several dozen enterprise-ready widgets -- including buttons, textboxes, form widgets with built-in validation, layout elements, and much more -- along with themes to lend them a consistent look. All of this is available for mobile environments as well.

• For working with advanced vector graphics, Dojo’s GFX API can render graphics in a wide variety of formats, with support for seamless manipulation (skewing, rotating, resizing), gradients, responding to mouse events, and more.

• The dojox/charting library supports powerful data visualization and dynamic charting, including a variety of 2D plots and animated charting elements.

• When you need feature-rich, lightweight, and mobile-friendly grids/tables, Dojo offers the dgrid widget, along with customizable default themes and accompanying features such as in-cell editing, row/cell selection, column resizing/reordering, keyboard handling, pagination, and more.

• Dojo is the officially supported framework for the ArcGIS API for JavaScript, one of the most widely used enterprise-grade APIs for web mapping and spatial analysis -- learning to use Dojo will open doors to creating richer web mapping applications using that API.

License and Copyright

The Dojo Toolkit (including this package) is dual licensed under BSD 3-Clause and AFL. For more information on the license please see the License Information. The Dojo Toolkit is Copyright (c) 2005-2018, JS Foundation. All rights reserved.

cli's Issues

create command

Create a new application:

dojo create myApp

Creating 'myApp'..
Doing something..
Doing something else..

All done! 
Why not try running your new app: 
cd myApp
dojo run

Add verbose mode to 'dojo version'

Under --verbose or similar, output the physical location of each installed command.
We should also update the dojo help text to include a section on command loading precedence (and add to the enhanced version command)

e.g.

$ dojo version -verbose

build (dojo-cli-build-webpack) 2.0.0 (global)
anothercommand (dojo-cli-another-command) 2.0.0 (/path/to/pwd/node_modules)

You are currently running dojo-cli 2.0.0

Command loading
------------------
Bit about where we look for commands and the resolution order...

Fix prepublish and travis config to get tests running

Updates to get tests running

• Dist is not ready / done yet
• Saucelabs are not used as this is node only

Automagically update commands

Extends #11

We should display which commands can be updated (where a more recent version is available):

dojo version

You are currently running:

dojo-cli-build-webpack 0.23.121 (can be updated)
dojo-cli-test 0.3.22 (can be updated)
...

On dojo-cli 2.1.223

Run 'dojo update' to update all commands to the latest versions.
Run 'dojo update -h' to see all the update options.

We will need to provide dojo update alongside this feature.

Cli executes the wrong command when multiple in group

The precedence order should favour local first, which the cli respects if you execute a command fully qualified e.g dojo build webpack. If you execute dojo build though the precedence is incorrect and the first one registered is executed.

Allow the CLI to load esModules

Commands written in TypeScript or Babel or similar add __esModule to the module to indicate that it came from an ESM module format. When this is present, load the .default command.

Default / first group commands should run without the command name

When registering dojo-cli-example-command it is expected that it should run when typing dojo cli example, but this is not currently the case.
Needs to be fixed.

versions doesn't report when there are later versions available

Versions does not work as expected, it does not report back that there are later versions even when there are.

Eject command

Our cli commands are meant to make the consumers code config free by internalising the config/config generation into the command itself. Given this, if a user needs more flexibility than the basic setup, we should allow them to "eject" those configs from the cli so they can use as a base for them to build on. This is an idea implemented in create-react-app.

The easiest way to implement this would just be to add an additional function to the command interface named eject, it is then up to the command to dump whatever config it has in files to the project.

Additional thoughts:

• Nearly all eject commands are going to want to add dependencies to the package.json, so we might want to implement a helper to do that.
• dojo eject seems like it should be an internal command to the cli. We don't have the concept of internal commands at the moment.

Documentation and Design of CLI

Dojo CLI

Purpose

The purpose of the cli is to enable users to get up and running as quickly as possible with dojo 2. It will provide project scaffolding and tasks commonly used during the development lifecycle. The cli will work based on providing it's users with a highly opinionated project structure utilising grunt, intern, typescript and stylus.

Install

To be installed globally via

npm install -g dojo-cli

Architecture

• The main module dojo-cli will be installed globally via npm and is essentially a task runner.
• The tasks will live in separate modules prefixed by dojo-cli-
• The dojo-cli module will search for tasks in the following locations:
  • dojo-cli’s node modules directory.
  • globally installed node_modules directory.
  • the consumer project's node_modules directory.
• This order ensures that tasks installed locally will take precedence over those which are globally installed or packaged within the cli.

Registering Tasks

Tasks must implement the task API.

Task Naming

Tasks will be implemented based on a strict package naming policy. Files will be named dojo-cli-<task>-<subtask>. eg. dojo-cli-build-rjs.

• There are no restrictions to the number or type of tasks and sub-tasks that can be registered.
• When only one sub-task is registered for a task type, it will be rolled up, ie. registering only dojo-cli-create-app will run when you enter dojo create.
• Registering multiple tasks of the same task type ie. dojo-cli-build-webpack and dojo-cli-build-rjs will generate two sub tasks under dojo build. They can be run with dojo build webpack and dojo build rjs respectively. Typing dojo build will display the list of available subtasks. ie.

You asked for 'build'. We found 2 'build' tasks: 'rjs' and 'webpack'.
You can run either 'dojo build rjs' or 'dojo build webpack'.

Arguments

Calling a task via dojo-cli will call the run function on the specified task. Any specified arguments will be passed through to the run function.

dojo test mocha --timeout=20000 === dojo-cli-test-mocha.run({timeout: 20000}

Default tasks (Not MVP)

Default tasks can be set using the dojo config command and are global defaults.
This could be used to define which subtask is ran when there are multiple under the same task type. ie. dojo config build.default rjs would ensure that dojo build ran the rjs task rather than showing the user available options.

Task API

description

Provides a description of the sub task to be displayed to the user.

name

Provides a name to be displayed to the user.

register

Registers the arguments that the sub task will accept and provides hints for those tasks to be displayed when --help is called.

run

The function to be ran when the task is executed. Will be passed the command line arguments.

options - Is this needed?

Updates

The CLI will inform the user when there is an update available to the dojo-cli core package.
Furthermore the user should be informed of any updates to it's installed tasks

test command

Implement the test command.

Options
None

Purpose
Runs all tests that have been created for a dojo application and outputs the results.

dojo test

Running tests..
Test results:

[test results go here]

CLI is too aggressive with empty directory detection

The cli should not include dotfiles when doing empty directory detection.

Example:

$ git init my-project
$ cd my-project
$ dojo new my-project

see Error: Directory is not empty even though all that is inside is the .git folder

Enhance `build` to produce layer files

A lá dojo1.

dojo build corporate - i.e. non FOSS build task

@rishson commented on Wed Sep 07 2016

The app needs to have a proper build step that produces a production version that is compressed, minified (maybe inlined) and obfuscated.

---

@kitsonk commented on Wed Sep 07 2016

obfuscated

Why?

compressed

What did you have in mind for this? Usually compression happens via the HTTP server, right?

(maybe inlined)

What did you have in mind for this? Are you suggesting bundled/concatenated into a single file? I would say that we should have a build the produces at least a base plus at least one layer/dynamically loaded bundle to prove out the build theories.

---

@rishson commented on Wed Sep 07 2016

Yep - I'm just thinking of the classic build steps. You're right, compression should really be minification in this example. You'd want to obfuscate so its harder to 'borrow' parts of your app, and minifiy for perf reasons. I agree about creating a layer file to test the build.

---

@rishson commented on Wed Sep 07 2016

Later on, we can do more advanced build steps, image compression, sprite generation from base images (for app icons etc), css minification...

---

@kitsonk commented on Wed Sep 07 2016

You'd want to obfuscate so its harder to 'borrow' parts of your app...

While I understand the potential corporate requirements for such things, I find that in open source software, promoting such practices as morally objectionable personally. Of course people are going to use obfuscators, but I think it really sends the wrong message if we actively enable or promote such activities. We get our strength from doing these sorts of things out in the open, and while we have chosen licensing that doesn't "infect" others with our philosophy (e.g. the GPL), I would prefer not to condone such practices.

---

@rishson commented on Wed Sep 07 2016

Depends who the majority users of D2 will be. If corporates, then they would expect some kind of uglification, because their app won't be FOSS. The more philosophical question is "is D2 FOSS that helps people primarily write FOSS, or closed source?" We can be both, but the build should default to one or the other. FWIW, the only closed source build steps I can think of right now are uglify and add license header to built assets.

---

@rishson commented on Wed Sep 07 2016

Maybe the build defaults to FOSS and we add an extra cli module that targets closed source? It could uglify, add license, check dependency tree for incompatible licenses ...

---

@kitsonk commented on Wed Sep 07 2016

UglifyJS I have no issues with, as it isn't really an obfuscator, but a minifier... To quote:

UglifyJS is a JavaScript parser, minifier, compressor or beautifier toolkit.

Just because that code is hard to unpick is a side-effect, versus an intent. I also would expect our build process to generate source maps though that go back to the original source for debugging purposes.

As far as "is D2 FOSS that helps people primarily write FOSS, or closed source?", my response to that Dojo Toolkit has been, and will continue to be, focused on developing open source software, which has flexible licensing that does not hinder further commercial use. I don't think we need to make a statement about the primary target of solutions written in Dojo 2. It isn't a binary decision and in my opinion isn't required to provide context to the development of Dojo 2.

We have seen many commercial organisation be able to build viable commercial business by being wholly open with their software, including Microsoft and TypeScript which we have built Dojo 2 on. Promoting or enabling patterns of being closed is not in the wider interest of the community. Actively hindering commercial reuse though, is in my opinion as closed as being closed source.

There are plenty of commercial organisation that will sell obfuscation solutions to enterprises. They are much better placed to assist organisations wishing to do so than the Dojo Toolkit.

---

@rishson commented on Wed Sep 07 2016

uglify -mangle -compress is very much obfuscation.
I'd agree on the sourcemaps though.

I'm fine with the default build being the best for FOSS, but still think there is a need for a more corporate focused alternative that does the tasks listed above + obfuscation.
It could be as simple as:

> uglify -mangle -compress -banner 'Some copyright statement with year indicator set automatically'
> [some check for copyleft licenses in the deployed app's dependency tree]

---

@rishson commented on Wed Sep 07 2016

@kitsonk I'm going to split this issue (turn this into a dojo build corporate issue, and create another issue that is the immediate build steps for the example app.

cli should be able to store basic config on a per command basis

Although the cli commands are designed to be mostly config free, it seems like in quite a few cases some basic preferences are desirable. An example of this would be the locale in cli-build, or the functional or unit test modes in cli-test

A command would be able to persist preferences for itself via a cli setter api - which would be then stored in a .dojorc at the project level. The command would receive preferences on load (and/or a getter api)

Refactor to separate out concerns of 'tty processing', 'loading commands' and 'running commands'

I think it would improve testability if we separated the code into:

1. tty processing using yargs
2. installed commands resolution and loading
3. running commands (in-built and installed)

Commands should not really be aware of their invocation context, i.e. that they are being run in a terminal.
This would make commands easier to test.
At the moment we have:
a command loader implementation (command) that knows about screen width.
a command loader (loadCommands) that knows about yargs
a command runner (registerCommands) that gets passed a command loader implementation for non-loader functionality.

I propose the following refactor:

command -> commandLoader
loadCommands -> runCommandLoader
registerCommands -> runCommands

where

index.ts is the only tty aware module
commandLoader is the only file system aware module
runCommandLoader becomes a simple loader executor
runCommands becomes a simple command executor
in-built commands become async commands in a /commands subdir and simply get added to the list of commands to run.
command specific text is kept with the command, rather than collected up into a cross-command text.ts file.
split commnds/version into the Command and the outdated check.

In addition, unit tests contain a test for index.ts. This is actually a functional test and should be moved into a function test dir, and should be tested against without mocks.

I think this is a cleaner separation of concerns that should be easier to test and extend.

help command

Implement the help command.

This command should aggregate all the available commands and output a list of available commands:

dojo help

Hey there, here are all the things you can do with dojo-cli:

help - shows all the available commands
create - creates a new dojo application
run - ...

For more information on any of these commands just run them with '-h',
e.g. 'dojo run -h' will give you the help for the 'run' command. 

(You are running dojo-cli 2.3.20)

It shouldn't output the full help for every command as that will get too verbose. The top level help command is basically a command discovery point.

Need to specify the versions of node that are compatible

Specify in package.json's engines.
Probably should transpile at least to support v4+ and other LTS versions.

Create example command for dojo-cli

To show potential users how to create a command we should create an example.
This will also help to prove the cli implementation approach.

TypeScript 2.0 for dojo/cli

Lint Command (tslint)

As our configs are to be kept internally when creating an app, we should add a lint command which runs tslint with a recommended set of config and output the results.
This can then be used as part of other commands.

Initial thoughts:

• The -eject functionality will spit out the tslint.json file
• The initial call to dojo lint will check for the existence of a tslint.json file and call it's own eject command if it does not exist.

readonly visibility modifier for TS2.0+

Dojo CLI Commands

Dojo CLI Commands

Proposed commands

create

dojo create <appName>

• Creates a new folder appName and inits a dojo2 application within.
• Will not proceed if the folder already exists
• Does not guide the user with a wizard
• Scaffolds an app with recommended components

test

dojo test [local | remote]

• Uses the intern test runner
• Optional arguments of local and remote

run (Not MVP)

dojo run [appName]

• Compiles code, starts http server, opens default browser
• Watches for changes and performs live reload?

build

dojo build

• Performs build
  • JS
  • HTML
  • CSS
• Creates .tgz file?
• Builds ready for deployment?
• watch?
• serve?

serve ??

dojo serve

• Runs http-server and opens browser to index.html

Correct the CLI prompt - dojo <group> <command> [options]

Prompt should be dojo <group> <command> [options]

Implement i18n into build process

Refs dojo/meta#55

Support multiple groups for a command

Currently a command can only provide for a single group and that group is decided by part of its package name ie dojo-cli-{groupname}-{command}.

it would be nice if in the command interface you can specify multiple groups or aliases. This is needed to support the dev task, which essentially desugars to the build task with some different arguments.

Semantics of dojo new

Currently dojo new takes a single param of appname, perhaps we should create a directory of appname.

Consider also adding dojo init which takes no params and inits a project in the current directory.

When the run promise is rejected, CLI should show the error message

When run function throws an error and it's promise rejects, the CLI should exit with an error message but currently does not.

Support @dojo scoped commands

We should support loading commands from @dojo scoped dependencies as well as dependencies prefixed with dojo-cli.

version command

This should output the versions of all registered groups, e.g.

dojo version

The currently installed groups are:

build (dojo/cli-build-webpack) 0.23.121
build (someAuthor/dojo-cli-MyBuildCommand) 1.2.3
test (dojo/cli-test) 0.3.22
...

You are currently running dojo-cli 2.1.223

Users can then copy and paste this info into issues raised on GH. This allows a user to provide version information as easily as possible, thus increasing the likelihood that they will include this information in GH issues.

Copy README into the release package

To get the README to show in npm we should copy the readme into the package as part of release tool.

Performance

Args are not passed when calling run through the command helper

The args are not passed to run when called via the command helper.

build command

Implement the build command:

dojo build

Building [app name].

Alias "build -w" with "dev" command

Implement the run command:

[inside the application dir]
dojo run

Running [app name] on http://localhost:[somePort]

[any important run info goes here, e.g. when a watch detects changes, recompilation errors]

CLI Pipelines

Details to follow

`dojo -v` Should show version number of dojo-cli

Help options misleading when more than one command for a group

If there are more than one command for a group the options reflect just one of the commands when using the dojo group -h, this is misleading.

Example, the first help output shows the two commands available under build but the options are only valid for the dojo build.

Command: dojo build -h

dojo build

Commands:
  dojo     Build dojo2 packages
  webpack  create a build of your application

Options:
  -h, --help     Show help                                             [boolean]
  -t, --type     type of build         [choices: "dev", "dist"] [default: "dev"]
  -v, --version  Show version number                                   [boolean]

Command: dojo build webpack -h

dojo build webpack

Options:
  -h, --help     Show help                                             [boolean]
  -w, --watch    watch and serve
  -p, --port     port to serve on when using --serve                    [number]
  -v, --version  Show version number                                   [boolean]

Command: dojo build dojo -h

dojo build dojo

Options:
  -h, --help     Show help                                             [boolean]
  -t, --type     type of build         [choices: "dev", "dist"] [default: "dev"]
  -v, --version  Show version number                                   [boolean]

CommandsMap is exposed in the Command interface - that bad mkay

😞 soz - leaky abstraction.

Hide built-in groups such as 'versions` from being listed in the installed commands.

We should hide built in groups such as versions so that we see:

$ dojo
dojo help

Usage: dojo <group> <command> [options]

Hey there, here are all the things you can do with dojo-cli:

Commands:
  build    create a build of your application

Options:
  -h, --help     Show help                                             [boolean]
  -v, --version  Show version number                                   [boolean]

For more information on any of these commands just run them with '-h'.

e.g. 'dojo run -h' will give you the help for the 'run' group of commands.

instead of:

$ dojo
dojo help

Usage: dojo <group> <command> [options]

Hey there, here are all the things you can do with dojo-cli:

Commands:
  build    create a build of your application
  version  List versions of registered commands

Options:
  -h, --help     Show help                                             [boolean]
  -v, --version  Show version number                                   [boolean]

For more information on any of these commands just run them with '-h'.

e.g. 'dojo run -h' will give you the help for the 'run' group of commands.

Publish the CLI interfaces

We should probably publish the CLI interfaces somewhere such that they can be used by cli commands.

At the moment a command would need to have a dependency on the cli itself in order to use it's interface and that is less than ideal.

Does not load globally installed commands

if a user has dojo-cli and for example dojo-cli-create-app both installed locally the cli should load the create-app command but it doesn't.

Fix the precedence ordering

Currently its possible to register multiple of the same command via global node_modules, the cli's node_modules, and the local projects node_modules. There is no distinguishing between what is registered when displayed either.

We should only support registering/displaying one command per namespace. And the precedence ordering should probably be: cli, global, local with local having the most precedence?

Remove `config`, `index` and `updateNotifier` from test coverage

The above mentioned files are not covered by tests because they are either config or untestable.
They need to be removed from test coverage using the intern excludeInstrumentation config argument.

Linking with CLI

Since we agreed to drop support for building packages from source, would it make sense to have a feature that allowed linking to local packages? Either through managing npm link or some other logical fashion.

version --outdated command

Refs #49 .
Implement version --outdated

CLI - MVP

cli is to be written in TS2 - including readOnly syntax.

Things to do first:

• document what @matt-gadd 's poc is doing. Document how we (sitepen) will write a new command, document how a 3rd party developer will write a new command.
• vertical slice: get create command to output its help text when dojo create -h is run.

Integrate css modules into build process

Refs dojo/widgets#66

cli should not error if no commands have implemented eject

Currently eject throws an error if no commands have implemented it, we should either not throw an error and report that now commands have implemented or not register the command if there are no available commands to eject,

CLI does not display error when invalid command provided

running a command that doesn't exist does not display any error/warning.