@telicent-oss/telicent-frontend-cli

Telicent Frontend CLI ("TEFE" CLI)

CLI package to capture & propagate Telicent frontend opinion on code, config & tools

Install this in each npm package repository to provide:

1. Some scripts to manually-trigger
   • idea: generate Telicent-flavoured™ Cypress config
2. Some scripts to use in hooks
   • idea: echo "tefe test-only-changed-files" >> ./husky/pre-commit
3. Some self-executing checks
   • idea: on CI, check yarn.lock didn't change after yarn install

And perhaps if we add globally-useful dev-scripts, we end up using this as a global install on our dev machines

Install

# Install within a package
cd <npm package directory>;
yarn add @telicent-oss/telicent-frontend-cli
# IMPORTANT: If you use `yarn` to install in local package, prefix with "yarn" (e.g. `yarn tefe`) to ensure you don't use a globally installed tefe

To test:

yarn tefe version # or `tefe version` for global version

Usage

All commands are available via tefe help:

Usage: tefe [options] [command]

Options:
  -h, --help               display help for command

Commands:
  version                  read version
  info                     Get context to help CLI developers
  hook-precommit           Telicent frontend precommit hook
  hook-postinstall         Telicent frontend postinstall hook
  config [options]         Show current directoryʼs ./tefe.config.json
  npmrc-authtoken [value]  Fetch NPM configuration tokens from the nearest
                           npmrc file (WARNING: Has limitations see
                           extractTokens.ts TODO)
  help [command]           display help for command

Note: This package uses update-notifier

To develop commands:

---

Tips

1. TypeScript source files import with .js extension e.g. import a from './path.js (as ./src/**/*.ts files are emitted and run from ./dist/**/*.js)

2. JavaScript test files must not include any extension in imports import a from './path';

3. CLI developer workflows require heavy use of symlinks via

   • yarn link
   • yarn unlink
   • And custom yarn relink command for forcing stubborn symlinks to reset

4. It might help to familiarise yourself with the general process of building CLI tools

Dev workflow

# To use (and develop) locally:
git clone git@telicent-oss/telicent-frontend-cli
cd telicent-frontend-cli
yarn link # creates symlink
# Sym-link/bin changes (e.g. package.json "bin" field) require:
yarn unlink && yarn link

Then for every local package you wish to use this cli:

cd <package>
yarn link @telicent-oss/telicent-frontend-cli

Or to use the package globally:

yarn global link @telicent-oss/telicent-frontend-cli

Best Practices

Automate - When you have an idea for a CLI task:

• Try to automate the task
• Else, try to automate part of the task
• Else, try to automate errors/warnings
• Else, create some feedback to help the next idea

Inter-operability: Bias for CLI scripts running (consistently) on as many different platforms as possible — including stripped down CI machines. So:

• avoid non-node code
• target node 16
• do not bundle, to allow easy ssh-debugging/editing of scripts on CI machines

Usefulness: Avoid being so precious about the code that nothing gets added