@travetto/repo/README.md

Monorepo utilities

<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify https://github.com/travetto/travetto/tree/main/module/repo/DOC.tsx and execute "npx trv doc" to rebuild -->
# Repo

## Monorepo utilities

**Install: @travetto/repo**
```bash
npm install @travetto/repo

# or

yarn add @travetto/repo
```

The repo module aims to provide concise monorepo based tools.  The monorepo support within the [Travetto](https://travetto.dev) framework, is based on [Npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)/[Yarn](https://yarnpg.com) workspaces.  This module is not a requirement for monorepo support, but provides some quality of life improvements for:
   *  Versioning releases
   *  Publishing releases
   *  Listing local modules
   *  Running commands on all workspace modules

## CLI - Version
The versioning operation will find all the changed modules (and the modules that depend on the changed), and will update the versions in accordance with the user preferences.  The versioning logic is backed by [Npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)'s and [Yarn](https://yarnpg.com)'s versioning functionality and so it is identical to using the tool manually. The determination of what has or hasn't changed is relative to the last versioning commit.

**Terminal: Version execution**
```bash
$ trv repo:version -h

Usage: repo:version [options] <level:major|minor|patch|premajor|preminor|prepatch|prerelease> [prefix:string]

Options:
  --mode <all|changed|direct>  The mode for versioning
  -f, --force                  Force operation, even in a dirty workspace (default: false)
  --commit, --no-commit        Produce release commit message (default: true)
  -m, --modules <string>       The module when mode is single
  -t, --tag                    Should we create a tag for the version
  -h, --help                   display help for command
```

Level is a standard semver level of: major, minor, patch or prerelease.  The prefix argument only applies to the prerelease and allows for determining the prerelease level.  For example:

**Terminal: Cutting a release candidate**
```bash
npx trv repo:version prerelease rc
```

After a release is cut, a new commit will be created that marks the next stable point in the commit history.

**Code: Versioning Commit**
```bash
commit e9dc1a1de9625ab47398997fee6a95dd5a426900
Author: Travetto Framework <travetto.framework@gmail.com>
Date:   Thu Feb 23 17:51:37 2023 -0500
Date:   Thu Feb 23 17:51:37 2023 -0500

    Publish @travetto/asset,@travetto/asset-web,@travetto/auth,@travetto/auth-model,@travetto/auth-web,@travetto/auth-web-jwt,@travetto/auth-web-passport,@travetto/auth-web-session,...
```

## CLI - Publish
The publish functionality is relatively naive, but consistent.  The code will look at all modules in the mono-repo and check the listed version against what is available in the npm registry.  If the local version is newer, it is a candidate for publishing.

**Terminal: Publish execution**
```bash
$ trv repo:publish -h

Usage: repo:publish [options]

Options:
  --dry-run, --no-dry-run  Dry Run? (default: true)
  -h, --help               display help for command
```

By default the tool will execute a dry run only, and requires passing a flag to disable the dry run.

**Terminal: Publishing changes**
```bash
npx trv repo:publish --no-dry-run
```

If no modules are currently changed, then the command will indicate there is no work to do, and exit gracefully.

## CLI - List
The listing functionality provides the ability to get the workspace modules in the following formats:

**Terminal: List execution**
```bash
$ trv repo:list -h

Usage: repo:list [options]

Options:
  -c, --changed                   Only show changed modules (default: false)
  -f, --format <graph|json|list>  Output format (default: "list")
  -fh, --from-hash <string>       Start revision to check against
  -th, --to-hash <string>         End revision to check against
  -h, --help                      display help for command
```

   *  `list` - Standard text list, each module on its own line
   *  `graph` - Modules as a digraph, mapping interdependencies
   *  `json` - Graph of modules in JSON form, with additional data (useful for quickly building a dependency graph)

**Terminal: List execution of Monorepo**
```bash
$ trv repo:list

global-test/model_auth-model
global-test/model_auth-session
global-test/model_cache
global-test/model_web-upload
global-test/pack_app
global-test/transformer-test
module/auth
module/auth-model
module/auth-session
module/auth-web
module/auth-web-passport
module/auth-web-session
module/cache
module/cli
module/compiler
module/config
module/context
module/di
module/doc
module/email
module/email-compiler
module/email-inky
module/email-nodemailer
module/eslint
module/image
module/log
module/manifest
module/model
module/model-dynamodb
module/model-elasticsearch
module/model-file
module/model-firestore
module/model-memory
module/model-mongo
module/model-mysql
module/model-postgres
module/model-query
module/model-query-language
module/model-redis
module/model-s3
module/model-sql
module/model-sqlite
module/openapi
module/pack
module/registry
module/repo
module/runtime
module/scaffold
module/schema
module/schema-faker
module/terminal
module/test
module/transformer
module/web
module/web-aws-lambda
module/web-connect
module/web-http-server
module/web-node
module/web-rpc
module/web-upload
module/worker
related/todo-app
```

## CLI - Exec
The exec command allows for running commands on all modules, or just changed modules.

**Terminal: Exec execution**
```bash
$ trv repo:exec -h

Usage: repo:exec [options] <cmd:string> [args...:string]

Options:
  -c, --changed                        Only changed modules (default: false)
  -w, --workers <number>               Number of concurrent workers (default: 9)
  --prefix-output, --no-prefix-output  Prefix output by folder (default: true)
  --show-stdout, --no-show-stdout      Show stdout (default: true)
  -h, --help                           display help for command
```

The standard format includes prefixed output to help identify which module produced which output.

**Terminal: List execution of Monorepo**
```bash
$ trv repo:exec -w 1 pwd

global-test/model_auth-model <workspace-root>/global-test/model_auth-model
global-test/model_auth-session <workspace-root>/global-test/model_auth-session
       global-test/model_cache <workspace-root>/global-test/model_cache
  global-test/model_web-upload <workspace-root>/global-test/model_web-upload
          global-test/pack_app <workspace-root>/global-test/pack_app
  global-test/transformer-test <workspace-root>/global-test/transformer-test
                   module/auth <workspace-root>/module/auth
             module/auth-model <workspace-root>/module/auth-model
           module/auth-session <workspace-root>/module/auth-session
               module/auth-web <workspace-root>/module/auth-web
      module/auth-web-passport <workspace-root>/module/auth-web-passport
       module/auth-web-session <workspace-root>/module/auth-web-session
                  module/cache <workspace-root>/module/cache
                    module/cli <workspace-root>/module/cli
               module/compiler <workspace-root>/module/compiler
                 module/config <workspace-root>/module/config
                module/context <workspace-root>/module/context
                     module/di <workspace-root>/module/di
                    module/doc <workspace-root>/module/doc
                  module/email <workspace-root>/module/email
         module/email-compiler <workspace-root>/module/email-compiler
             module/email-inky <workspace-root>/module/email-inky
       module/email-nodemailer <workspace-root>/module/email-nodemailer
                 module/eslint <workspace-root>/module/eslint
                  module/image <workspace-root>/module/image
                    module/log <workspace-root>/module/log
               module/manifest <workspace-root>/module/manifest
                  module/model <workspace-root>/module/model
         module/model-dynamodb <workspace-root>/module/model-dynamodb
    module/model-elasticsearch <workspace-root>/module/model-elasticsearch
             module/model-file <workspace-root>/module/model-file
        module/model-firestore <workspace-root>/module/model-firestore
           module/model-memory <workspace-root>/module/model-memory
            module/model-mongo <workspace-root>/module/model-mongo
            module/model-mysql <workspace-root>/module/model-mysql
         module/model-postgres <workspace-root>/module/model-postgres
            module/model-query <workspace-root>/module/model-query
   module/model-query-language <workspace-root>/module/model-query-language
            module/model-redis <workspace-root>/module/model-redis
               module/model-s3 <workspace-root>/module/model-s3
              module/model-sql <workspace-root>/module/model-sql
           module/model-sqlite <workspace-root>/module/model-sqlite
                module/openapi <workspace-root>/module/openapi
                   module/pack <workspace-root>/module/pack
               module/registry <workspace-root>/module/registry
                   module/repo .
                module/runtime <workspace-root>/module/runtime
               module/scaffold <workspace-root>/module/scaffold
                 module/schema <workspace-root>/module/schema
           module/schema-faker <workspace-root>/module/schema-faker
               module/terminal <workspace-root>/module/terminal
                   module/test <workspace-root>/module/test
              related/todo-app <workspace-root>/related/todo-app
            module/transformer <workspace-root>/module/transformer
                    module/web <workspace-root>/module/web
         module/web-aws-lambda <workspace-root>/module/web-aws-lambda
            module/web-connect <workspace-root>/module/web-connect
        module/web-http-server <workspace-root>/module/web-http-server
               module/web-node <workspace-root>/module/web-node
                module/web-rpc <workspace-root>/module/web-rpc
             module/web-upload <workspace-root>/module/web-upload
                 module/worker <workspace-root>/module/worker
```