dojo / cli Goto Github PK
View Code? Open in Web Editor NEW:rocket: Dojo - command line tooling.
Home Page: http://dojo.io
License: Other
:rocket: Dojo - command line tooling.
Home Page: http://dojo.io
License: Other
Specify in package.json
's engines
.
Probably should transpile at least to support v4+ and other LTS versions.
Refs dojo/meta#55
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:
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.😞 soz - leaky abstraction.
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]
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]
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.
The args are not passed to run when called via the command helper.
Details to follow
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,
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.
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.
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.
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:
-eject
functionality will spit out the tslint.json
filedojo lint
will check for the existence of a tslint.json
file and call it's own eject
command if it does not exist.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
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
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.
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.
cli
is to be written in TS2 - including readOnly syntax.
Things to do first:
create
command to output its help text when dojo create -h
is run.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
.
To be installed globally via
npm install -g dojo-cli
dojo-cli
will be installed globally via npm
and is essentially a task runner.dojo-cli-
dojo-cli
module will search for tasks in the following locations:
dojo-cli’s
node modules directory.Tasks must implement the task API
.
Tasks will be implemented based on a strict package naming policy. Files will be named dojo-cli-<task>-<subtask>
. eg. dojo-cli-build-rjs
.
tasks
and sub-tasks
that can be registered.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
.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'.
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 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.
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?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
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.
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.
To show potential users how to create a command we should create an example.
This will also help to prove the cli
implementation approach.
A lá dojo1.
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.
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.
dojo create <appName>
appName
and inits a dojo2 application within.dojo test [local | remote]
intern
test runnerlocal
and remote
dojo run [appName]
http
server, opens default browserdojo build
.tgz
file?dojo serve
index.html
When run
function throws an error and it's promise rejects, the CLI should exit with an error message but currently does not.
Refs #49 .
Implement version --outdated
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.
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...
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.
Implement the build
command:
dojo build
Building [app name].
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?
@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.
Prompt should be dojo <group> <command> [options]
I think it would improve testability if we separated the code into:
yargs
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.
To get the README to show in npm we should copy the readme into the package as part of release tool.
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]
running a command that doesn't exist does not display any error/warning.
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.
Versions does not work as expected, it does not report back that there are later versions even when there are.
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)
Refs dojo/widgets#66
We should support loading commands from @dojo scoped dependencies as well as dependencies prefixed with dojo-cli
.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.