Nest CLI

[maximousblk]

Nest CLI

• Use the latest standard modules as much as possible
• Use ASCII for stdout as much as possible (looking at you cliffy)
• Avoid using --unstable APIs
• Store all config in a temporary .nest directory
• Exclude all dotfiles by default while publishing
• Enforce semver
• Companion server for gui (see Nest GUI #9)

Commands

nest register # opens the register page in browser

nest login # prompt for login info
nest login --token <token> # add access to an account

nest logout # logout of current account
nest logout --token <token> # remove access to an account

nest # asks to initialize a new module or link an existing one

  # if a module is already initialized and linked, just sync the metadata

  # Nest CLI 1.0.0
  # ? setup "~/mod"? [Y/n]:
  # ? link to an existing module? [Y/n]:
  # ? what's the name of your existing module? (mod):
  # i linked to "user/mod" (created .nest and added it to .gitignore)

  # Nest CLI 1.0.0
  # ? Setup "~/mod"? [Y/n]:
  # ? Link to an existing module? [Y/n]: n
  # ? Module name (mod):
  # ? Version (0.1.0):
  # ? Description:
  # ? Homepage:
  # i Linked to "user/mod" (created .nest and added it to .gitignore)

nest init # initialize a new module in current directory

nest init <name> # initialize a new module in specified directory

nest setup <name> # link current directory to an existing module

nest settings # opens user settings in editor

nest config # opens module config in editor

nest publish --git # publish the latest local git tag

nest publish [ <version> || patch || minor || major ] [ --pre <id> ] # publish the specified version

  # say the current version is module@1.0.0

  # nest publish                    module@1.0.1
  # nest publish 1.2.3              module@1.2.3
  # nest publish patch              module@1.0.1
  # nest publish minor              module@1.1.0
  # nest publish major              module@2.0.0

  # nest publish --pre              module@1.0.1-0
  # nest publish 1.2.3 --pre        module@1.2.3-0
  # nest publish patch --pre        module@1.0.1-0
  # nest publish minor --pre        module@1.1.0-0
  # nest publish major --pre        module@2.0.0-0

  # nest publish --pre alpha        module@1.0.1-alpha.0
  # nest publish 1.2.3 --pre beta   module@1.2.3-beta.0
  # nest publish patch --pre broke  module@1.0.1-broke.0
  # nest publish minor --pre asdf   module@1.1.0-asdf.0

nest audit # returns an audit report

nest upgrade # upgrade nest cli

# to do any task in the gui, add a --gui or -G flag
# to disable confirmation prompts, add a --yes or -Y flag

Configuration

// .nest/module.json

{
  "$schema": "https://nest.land/-/nest-cli/schema.json",

  "name": "mod",
  "full_name": "My Awesome Module",
  "description": "I swear my module is the best out there",
  "homepage": "https://my.awesome.module",
  "license": "LICENSE",

  "hooks": {
    "presync": "command",
    "postsync": "command",
    "prepack": "command",
    "postpack": "command",
    "prepublish": "command",
    "postpublish": "command",
    "preaudit": "command",
    "postaudit": "command"
  },

  "unlisted": false,
  "private": false
  // ...
}

config schema

// .nest/module.json interface
interface Module {
  $schema: string;

  name: string;
  fullName?: string; // default: `${name}`
  description?: string; // default: ""
  homepage?: string; // default: ""
  license?: string; // default: "UNKNOWN"
  unlisted?: boolean; // default: false
  hooks: {
    presync: string; // default: ""
    postsync: string; // default: ""
    prepack: string; // default: ""
    postpack: string; // default: ""
    prepublish: string; // default: ""
    postpublish: string; // default: ""
  };
  // ...
}

// .nest/data.json

// THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.

{
  "meta": {
    "name": "mod",
    "full_name": "My Awesome Module",
    "description": "I swear my module is the best out there",
    "homepage": "https://my.awesome.module",
    "license": "LICENSE",
    "unlisted": false,
    // ...
    "hooks": {
      "presync": "command",
      "postsync": "command",
      "prepack": "command",
      "postpack": "command",
      "prepublish": "command",
      "postpublish": "command",
    },
  },
  // cache the api for offline use
  "api": {
    "versions": ["1.0.0", "0.9.8", "0.9.7", "..."],
    "latestVersion": "1.0.0",
    "lastPublished": 1603171976111,
    "license": "MIT"
    // ...
  },
  "version": "1.0.0", // nest cli version
  "lastSync": 1602831956336,
  "nextAutoSync": 1602832005131
  // ...
}

# .nest/ignore

@extends .gitignore

docs/
tests/
CHANGELOG
CODE_OF_CONDUCT.md
CONTRIBUTING.md
funding.yml

# all dot files are ignored by default so user needs to include them
!.shared_dot_file
!.shared_dot_directory/

<!-- .nest/README.md -->

> Why do I have a directory named ".nest" in my project?

The ".nest" directory is created when you link a directory to a Nest module.

> What does this directory contain?

The "module.json" file contains metadata about the module

The "ignore" file contains a list of files that are ignored or included

The "data.json" file is an auto generated file. This file should **NOT** be directly edited by the user.

> Should I commit the ".nest" directory?

**No**, you should not commit the ".nest" directory to your repository.
Upon creation, it will be automatically added to your ".gitignore" file.

Publishing Programmatically

People can programmatically publish the modules using the nest module (same as cli)

import { publish } from "https://nest.land/-/nest@1.0.0/src/utils/publish.ts"

const options = {
  // ...
})

// auth details are taken from the `DENO_AUTH_TOKENS` env var

publish("module", options);

Notes

• Anything that could lead to unwanted consequences, should be handled by the GUI or the website. These features should never be able to be automated and require human interaction.

• yolk should be merged into cli, though still be usable as a module.

Why are Nest CLI and eggs separate?

Nest CLI is the main utility you would use to create and publish modules. eggs on the other hand, is just a reference module manager that has first-class support for Nest including private modules. Other module managers can use this reference to integrate Nest into their software.

[t8]

1.0.0 bare minimum CLI requirements

• Setup
  • Configuration
    • Published to Arweave (See RFC)
    • Entry file optional
• Linking command for API keys and keyfiles (need to support multiple)
  • Support logging in with username / password
• Publishing functionality

Nice Features

• audit
• upgrade
• settings
• config

CLI written in Deno

[SteelAlloy]

nest publish [ <version> || patch || minor || major ] [ --pre <id> ] # publishes the specified version

  # say the current version is module@1.0.0

  # nest publish                    => module@1.0.1
  # nest publish 1.2.3              => module@1.2.3
  # nest publish patch              => module@1.0.1
  # nest publish minor              => module@1.1.0
  # nest publish major              => module@2.0.0

  # nest publish --pre              => module@1.0.1-0
  # nest publish 1.2.3 --pre        => module@1.2.3-0
  # nest publish patch --pre        => module@1.0.1-0
  # nest publish minor --pre        => module@1.1.0-0
  # nest publish major --pre        => module@2.0.0-0

  # nest publish --pre alpha        => module@1.0.1-alpha.0
  # nest publish 1.2.3 --pre beta   => module@1.2.3-beta.0
  # nest publish patch --pre broke  => module@1.0.1-broke.0
  # nest publish minor --pre asdf   => module@1.1.0-asdf.0
  # nest publish major --pre bruh   => module@2.0.0-bruh.0

According to the SemVer Standard, # nest publish --pre => module@1.0.1-0 is incorrect 😕

semver.inc("1.0.0", "patch")
1.0.1
semver.inc("1.0.0", "minor")
1.1.0
semver.inc("1.0.0", "major")
2.0.0
semver.inc("1.0.0", "prepatch")
1.0.1-0
semver.inc("1.0.0", "preminor")
1.1.0-0
semver.inc("1.0.0", "premajor")
2.0.0-0
semver.inc("1.0.0", "prerelease")
1.0.1-0
semver.inc("1.0.0", "pre")
1.0.0-0

We maybe need to introduce --prerelease

[maximousblk]

Sorry for not mentioning it.

nest publish
# is the same as
nest publish patch

so

nest publish --pre
# is the same as
nest publish patch --pre

This is because patch will be the default constraint if user doesn't specify it.

[SteelAlloy]

https://github.com/nestdotland/nest/projects/1