Astrohelm default workspace

Installation guide 🚀

First step: workspace installation

Use next commands to install and update your workspace Or use this repository as a template repository, if so - you can skip this step.

  # Download repository
  git clone https://github.com/astrohelm/node-workspace
  rm -rf ./path/to/workspace/.git ./path/to/workspace/package-lock.json
  cd ./path/to/workspace/
  # Update and install dependencies
  ncu -u
  npm i
  # Update node.js (optional()
  nvm install latest
  nvm use latest

Second step: Package personalization

Update package json, all with prefix your-
If your nodejs version newer than package.json current add || your-node-version.

// package.json
{
  "license": "MIT",
  "version": "0.0.1",
  "type": "commonjs",
  "name": "your-package-name",
  "homepage": "https://astrohelm.ru",
  "description": "your-package-description",
  "author": "your-name <your-mail>",
  "keywords": ["your-keyword #1", "your-keyword #n"],

  "main": "index.js",
  "types": "types/index.d.ts",
  "packageManager": "[email protected]",
  "readmeFilename": "README.md",
  "engines": { "node": "18 || 19 || 20" },
  "browser": {},
  "files": ["/dist", "/lib", "/types"],

  "scripts": {
    "test": "node --test && tsc",
    "dev": "node index.js",
    "prettier:fix": "prettier --write \"**/*.{js,ts,json,html,cjs,md,yaml}\"",
    "eslint:fix": "eslint --fix \"**/*.{js,ts}\""
  },

  "repository": { "type": "git", "url": "git+https://github.com/astrohelm/your-package-name.git" },
  "bugs": { "url": "https://github.com/astrohelm/your-package-name/issues", "email": "your-mail" },

  "devDependencies": {
    "@types/node": "^18.15.10",
    "eslint": "^8.40.0",
    "eslint-config-astrohelm": "^1.0.0",
    "eslint-config-prettier": "^8.8.0",
    "eslint-plugin-import": "^2.27.5",
    "eslint-plugin-prettier": "^4.2.1",
    "prettier": "^2.8.8",
    "typescript": "^5.0.2"
  }
}

Third step: About files

Go to CHANGELOG.md and update it for your package. WARNING ! Don't fotget about date (xxxx-xx-xx).

<!-- CHANGELOG.md -->

# Changelog

## [Unreleased][unreleased]

## [0.0.1][] - xxxx-xx-xx

- Stable release version
- Repository created

[unreleased]: https://github.com/astrohelm/your-package-name/compare/v0.0.1...HEAD
[0.0.1]: https://github.com/astrohelm/your-package-name/releases/tag/v0.0.1

Update AUTHORS

 <!-- AUTHORS -->

your-name <your-mail>

Almost last step: Update README.md

Replace your README.md with next information and change Your-package-name to actual.

<!-- README.md -->
<h1 align="center">Your-package-name v0.0.1</h1>

<h2 align="center">Initial release 🚀</h2>

<h2 align="center">Copyright & contributors</h2>

<p align="center">
Copyright © 2023 <a href="https://github.com/astrohelm/Your-package-name/graphs/contributors">Astrohelm contributors</a>.
Your-package-name is <a href="./LICENSE">MIT licensed</a>.<br/>
Your-package-name is part of <a href="https://github.com/astrohelm">Astrohelm ecosystem</a>.
</p>

Last step: Save results

WARNING ! Update this file before moving throw this step.

Create a new package in [organization][https://github.com/astrohelm/] repository. Use next commands to save you package.

git init
git remote add origin your-package-location
# Start from here, if you used template
git branch -M main # if your default branch is not main
git commit -am "Repository init"
git tag v0.0.1
git push origin main
git push origin v0.0.1
git checkout -b dev
git push origin dev

Return to your organization repository and do:

Add keywords
Update description
Draft release with v0.0.1 tag and v0.0.1 as a title and updated README file as description.

If you creating library you may publish it now to npm with npm publish command.

Congratulations, package initialized 🚀

About files & structure

This workspace have commonjs in use by default. You can switch it in package.json if you want.

dist directory used for fronted package analog. You can use it if your package is multi-platform based.
eslint astrohelm eslint rules
types .d.ts library types exports
CHANGELOG.md in use for project history documentation
Makefile ultimate commands shortcuts creator
tests here you can put all test coverage of your package
.github github ci pipeline by default
lib folder should contain all you library logic, WARNING ! Remove if you not writing library. Replace with src folder.

Copyright & contributors

CLI V1.0.0 setup

Describe the solution

My vision of CLI Builder usage:

CLI Builder

I think we need to step back from functional chaining and make contracts configurable by object argument. On another hand - we can support both strategies

const { Command } = require('astrocli');
const cli = new Command({  
  // In case, if missing one of the fields
  // You can parse it from package.json
  name: 'cli',
  description: 'Custom cli',
  version: '1.0.0', 
  arguments: [],
  options: { 
     h: { alias: 'help', type: 'void' },
  }, 
  action: (args, options) => {
    if(option.h) cli.execute();
    else console.log('No command found');
  },
  commands: { // We can handle Map too
    // Equivalent to new calculate: Command({ ... }),
    calculate: {
      example: 'libname calcaulate --alpha 2 -b 3 +',
      description: 'Return calculation of a & b',
      arguments: [['string', '- or +']],
      // Might be as async and sync 
      // You need to wait until resolve 
      // To prevent cli trashing
      action: (args, opts) => {
        const sign = args[0] === '-' ? -1 : 1;
        console.log(opts.a + opts.b * sign);
      },
      options: { 
        // If no default - required
        a: { alias: ['alpha', 'first'], type: 'number', default: 0 },
        b: { alias: 'beta', type: 'number' },
      }
    }
  }
});

Other methods

 //      writable stream       readable stream         to parse ENV Variables
 const { stdin: console.stdin, stdout: console.stdout, process } = options;
 const { input, select, checkbox, confirm, loader } = require('astocli');
 // Input example, other contracts on your choice
 (async () => {
   const clear = true; // Clear prompt on promise resolve
   const message = 'Your name:'; // Required
   const default = 'Anonymous'; // Not required
   const validate = input => input.length > 5; // Not required
   // Also validate can return String, that would be output for user
   // Promise would not resolve while user pass incorrect values 
   const result = await input({ message, default, validate }, options);
   console.log(result); // Alexander
   // input({ message, default, validate, clear }).cancel(); 
   // Should close input and return fulfilled promise
 });

Additional context

Usage case

In my case of usage, it will be used from bin folder to create cli, for example to handle init process.

./bin/index.js

#!/usr/bin/env node
'use strict';

const CLI = require('astrocli');
// ...

./package.json

{
 "name": "name",
 "bin": "./bin/index.js", 
 "dependencies": {
   "astrocli": "^1.0.0"
 },
}

bash

# If installed
name --init
# Otherwise
npx create-name

Colors

You can colorize your output, to make it more readable with

console.log('\x1b[36m > \x1b[0m', 'Message');  // Consant
console.log("\x1b[38;2;" + 255 + ";" + 255 + ";" + 255 + "m" + _text + "\x1b[0m"); // RGB

You can make it configurable, if you want.

Commands suggestion

$ libname calc -a 1 -b 2 +
error: unknown command calc
(Did you mean calculate ?)
$ libname calculate -alpa 1 -b 2 +
error: unknown option -alpa
(Did you mean --alpha ?)

astrohelm / astrocli Goto Github PK

astrocli's Introduction