feat: add mason new command

CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.0.1-dev.15
+
+- feat: add `mason new` to create a new brick
+- feat: `mason init` sets up bricks with sample
+- fix: support bricks without `vars`
+- fix: support bricks with empty `vars`
+- docs: revamp README to include `Quick Start` section
+
 # 0.0.1-dev.14
 
 - fix: mason init path resolution

README.md

@@ -7,97 +7,50 @@ A template generator which helps teams generate files quickly and consistently.
 
 Mason allows developers to create and consume resuable templates call bricks.
 
-## Activating Mason
+## Quick Start
 
-`pub global activate mason`
+### Activate Mason
 
-## Creating Custom Brick Templates
-
-### Create a Brick YAML
-
-The `brick.yaml` contains metadata for a `brick` template.
-
-`brick.yaml`
-
-```yaml
-name: greetings
-description: A Simple Greetings Brick
-vars:
-  - name
-```
-
-### Create a Brick Template
-
-Write your brick template in `__brick__` using [mustache templates](https://mustache.github.io/). See the [mustache manual](https://mustache.github.com/mustache.5.html) for detailed usage information.
-
-`__brick__/greetings.md`
-
-```md
-# Greetings {{name}}!
-```
-
-❗ **Note: bricks can consist of multiple files and subdirectories**
-
-#### File Resolution
-
-It is possible to resolve files based on path input variables using the `<% %>` tag.
-
-For example, given the following `brick.yaml`:
-
-```yaml
-name: app_icon
-description: Create an app_icon file from a URL
-vars:
-  - url
+```sh
+$ pub global activate mason
 ```
 
-And the following brick template:
-
-`__brick__/<% url %>`
-
-Running `mason make app_icon -- --url path/to/icon.png` will generate `icon.png` with the contents of `path/to/icon.png` where the `path/to/icon.png` can be either a local or remote path.
-
-## Consuming Brick Templates
-
-### Create a Mason YAML
+### Initialize Mason
 
 ```sh
 $ mason init
 ```
 
-Add bricks to the newly generated `mason.yaml`:
+`mason init` initializes the Mason CLI in the current directory.
+
+Running `mason init` generates a `mason.yaml` and an example `brick` so that you can get started immediately.
 
 ```yaml
 bricks:
-  greetings:
-    path: bricks/greetings
-  todos:
-    git:
-      url: [email protected]:felangel/mason.git
-      path: bricks/todos
+  hello:
+    path: bricks/hello
 ```
 
-Then you can use `mason make <greetings|todos>`:
+Then you can use `mason make` to generate your first file:
 
 ```sh
-mason make greetings
-mason make todos
+mason make hello
 ```
 
 ### Command Line Variables
 
 Any variables can be passed as command line args.
 
 ```sh
-$ mason make greetings -- --name Felix
+$ mason make hello -- --name Felix
 ```
 
 ### Variable Prompts
 
 Any variables which aren't specified as command line args will be prompted.
 
 ```sh
-$ mason make greetings
+$ mason make hello
 name: Felix
 ```
 
@@ -106,23 +59,75 @@ name: Felix
 Any variables can be passed via json file:
 
 ```dart
-$ mason make greetings --json greetings.json
+$ mason make hello --json hello.json
 ```
 
-where `greetings.json` is:
+where `hello.json` is:
 
 ```json
 {
   "name": "Felix"
 }
 ```
 
-The above commands should all generate `GREETINGS.md` in the current directory with the following content:
+The above commands will all generate `HELLO.md` in the current directory with the following content:
 
 ```md
-# Greetings Felix!
+# Hello Felix!
 ```
 
+## Creating New Bricks
+
+Create a new brick using the `mason new` command.
+
+```sh
+$ mason new <BRICK_NAME>
+```
+
+The above command will generate a new brick in the `bricks` directory with an example `brick.yaml` and `__brick__` template directory.
+
+### Brick YAML
+
+The `brick.yaml` contains metadata for a `brick` template.
+
+```yaml
+name: greetings
+description: A Simple Greetings Brick
+vars:
+  - name
+```
+
+### Brick Template
+
+Write your brick template in the `__brick__` directory using [mustache templates](https://mustache.github.io/). See the [mustache manual](https://mustache.github.com/mustache.5.html) for detailed usage information.
+
+`__brick__/greetings.md`
+
+```md
+# Greetings {{name}}!
+```
+
+❗ **Note: `__brick__` can contain multiple files and subdirectories**
+
+#### File Resolution
+
+It is possible to resolve files based on path input variables using the `<% %>` tag.
+
+For example, given the following `brick.yaml`:
+
+```yaml
+name: app_icon
+description: Create an app_icon file from a URL
+vars:
+  - url
+```
+
+And the following brick template:
+
+`__brick__/<% url %>`
+
+Running `mason make app_icon -- --url path/to/icon.png` will generate `icon.png` with the contents of `path/to/icon.png` where the `path/to/icon.png` can be either a local or remote path.
+
 ## Usage
 
 ```sh
@@ -136,6 +141,7 @@ Global options:
     --version    Print the current version.
 
 Available commands:
-  init   Initialize a new mason.yaml.
+  init   Initialize mason in the current directory.
   make   Generate code using an existing brick template.
+  new    Creates a new brick template.
 ```

bin/mason.dart

@@ -16,7 +16,8 @@ void main(List<String> args) async {
           help: 'Print the current version.',
         )
         ..addCommand(InitCommand(logger))
-        ..addCommand(MakeCommand(logger));
+        ..addCommand(MakeCommand(logger))
+        ..addCommand(NewCommand(logger));
 
   try {
     final globalArgs = masonCli.argParser.parse(args);

lib/src/brick_yaml.dart

@@ -12,9 +12,8 @@ class BrickYaml {
   const BrickYaml(
     this.name,
     this.description,
-    this.vars, {
-    String brick,
-  }) : brick = brick ?? '__brick__';
+    this.vars,
+  );
 
   /// Converts [Map] to [BrickYaml]
   factory BrickYaml.fromJson(Map<dynamic, dynamic> json) =>
@@ -27,16 +26,16 @@ class BrickYaml {
   /// `brick.yaml`
   static const file = 'brick.yaml';
 
+  /// static constant for brick template directory name.
+  /// `__brick__`
+  static const dir = '__brick__';
+
   /// Name of the brick.
   final String name;
 
   /// Description of the brick.
   final String description;
 
-  /// Optional path to brick template directory.
-  /// Defaults to `__brick__`.
-  final String brick;
-
   /// List of variables used when templating a brick.
   final List<String> vars;
 }

lib/src/commands/commands.dart

@@ -1,2 +1,3 @@
 export 'init_command.dart';
 export 'make_command.dart';
+export 'new_command.dart';

lib/src/commands/init_command.dart

@@ -5,6 +5,7 @@ import 'package:io/ansi.dart';
 import 'package:mason/src/generator.dart';
 import 'package:path/path.dart' as p;
 
+import '../brick_yaml.dart';
 import '../logger.dart';
 import '../mason_yaml.dart';
 
@@ -18,7 +19,7 @@ class InitCommand extends Command<dynamic> {
   final Logger _logger;
 
   @override
-  final String description = 'Initialize a new ${MasonYaml.file}.';
+  final String description = 'Initialize mason in the current directory.';
 
   @override
   final String name = 'init';
@@ -41,7 +42,10 @@ class InitCommand extends Command<dynamic> {
     final fetchDone = _logger.progress('Initializing');
     final target = DirectoryGeneratorTarget(cwd, _logger);
     final generator = _MasonYamlGenerator();
-    await generator.generate(target);
+    await generator.generate(
+      target,
+      vars: <String, String>{'name': '{{name}}'},
+    );
     fetchDone('Initialized');
     _logger
       ..info(
@@ -56,18 +60,39 @@ class _MasonYamlGenerator extends MasonGenerator {
       : super(
           '__mason_init__',
           'Initialize a new ${MasonYaml.file}',
-          files: [TemplateFile(MasonYaml.file, _content)],
+          files: [
+            TemplateFile(MasonYaml.file, _masonYamlContent),
+            TemplateFile(
+              p.join('bricks', 'hello', BrickYaml.file),
+              _brickYamlContent,
+            ),
+            TemplateFile(
+              p.join('bricks', 'hello', BrickYaml.dir, 'HELLO.md'),
+              'Hello {{name}}!',
+            ),
+          ],
         );
 
-  static const _content =
+  static const _brickYamlContent = '''name: hello
+description: An example hello brick.
+vars:
+  - name
+''';
+
+  static const _masonYamlContent =
       '''# Register bricks which can be consumed via the Mason CLI.
 # https://pub.dev/packages/mason
 bricks:
-  # Sample Greeting Brick
-  # Run `mason make greeting` to try it out.
-  greeting:
-    git:
-      url: [email protected]:felangel/mason.git
-      path: bricks/greeting
+  # Sample Brick
+  # Run `mason make hello` to try it out.
+  hello:
+    path: bricks/hello
+  # Bricks can also be imported via git url.
+  # Uncomment the following lines to import
+  # a brick from a remote git url.
+  # todos:
+  #   git:
+  #     url: [email protected]:felangel/mason.git
+  #     path: bricks/todos
 ''';
 }