Commands

  Validates the workspace.

  poly check [:dev]

  Prints 'OK' and returns 0 if no errors were found.
  If errors or warnings were found, show messages and return the error code,
  or 0 if only warnings. If internal errors, 1 is returned.

  Error 101 - Illegal dependency on namespace.
    Triggered if a :require statement refers to a component namespace
    other than interface. Examples of valid namespaces:
     - com.my.company.mycomponent.interface
     - com.my.company.mycomponent.interface.subns
     - com.my.company.mycomponent.interface.my.subns

  Error 102 - Function or macro is defined twice.
    Triggered if a function or macro is defined twice in the same namespace.

  Error 103 - Missing definitions.
    Triggered if a def, defn or defmacro definition exists in one component's
    interface but is missing in another component that uses the same interface.

  Error 104 - Circular dependencies.
    Triggered if circular dependencies were detected, e.g.:
    Component A depends on B that depends on A (A > B > A), or A > B > C > A.

  Error 105 - Illegal name sharing.
    Triggered if a base has the same name as a component or interface.
    Projects and profiles can be given any name.

  Error 106 - Multiple components that share the same interfaces in a project.
    Triggered if a project contains more than one component that shares the
    same interface.

  Error 107 - Missing components in project.
    Triggered if a component depends on an interface that is not included in the
    project. The solution is to add a component to the project that
    implements the interface.

  Error 108 - Components with an interface that is implemented by more than one
              component are not allowed for the development project.
    The solution is to remove the component from the development project
    and define the deps/paths for each component in separate profiles
    (including test paths).

  Error 109 - Invalid test runner configuration for some projects.
    The value of the optional :create-test-runner key under [:test] or
    [:projects "some-project-name" :test] in workspace.edn must be either
    nil, :default, or a fully qualified symbol referring to a function on
    the poly tool's classpath, which can take a single argument and must return
    an instance of polylith.clj.core.test-runner-contract.interface/TestRunner.

  Error 110 - Invalid config file.
    Triggered if a deps.edn file for a brick or project is invalid.
    It's allowed to omit the deps.edn file entirely, except for development,
    and in that case the brick/project will be ignored.

  Error 111 - Unreadable namespace in brick/project.
    Triggered if a namespace can't be parsed for a brick or project.
    The solution is to fix the invalid namespace (add it if missing)
    or move the file from 'src' to 'resources'.

  Warning 201 - Mismatching argument lists in function or macro.
    Triggered if a function or macro is defined in the interface for a component
    but also defined in the same interface for another component but with a
    different argument list.

  Warning 202 - Missing paths in project.
    Triggered if a path in a project doesn't exist on disk.
    The solution is to add the file or directory, or to remove the path.

  Warning 203 - Path exists in both dev and profile.
    It's discouraged to have the same path in both the development project
    and a profile. The solution is to remove the path from dev or the profile.

  Warning 205 - Non top namespace was found in brick.
    Triggered if a namespace in a brick doesn't start with the top namespaces
    defined in :top-namespace in ./workspace.edn.

  Warning 207 - Unnecessary components were found in project.
    Triggered if components were defined in a project that are not used by any of
    its bricks. Development is only checked if :dev is passed in and is only performed
    by the check command (not test and info). To ignore this warning, put the component
    name in the :necessary vector for a project in :projects in ./workspace.edn.
    See an example here: https://github.com/polyfy/polylith/blob/master/workspace.edn

  Creates a component, base, project or workspace.

  poly create TYPE [ARGS]

    TYPE = c[omponent] -> Creates a component.
           b[ase]      -> Creates a base.
           p[roject]   -> Creates a project.
           w[orkspace] -> Creates a workspace.

    ARGS = Varies depending on TYPE.

  To get help for a specific TYPE, execute 'poly help create TYPE'.

  Example:
    poly create c name:user
    poly create component name:user
    poly create component name:admin interface:user
    poly create base name:mybase
    poly create project name:myproject
    poly create workspace name:myws top-ns:com.my.company
    poly create workspace name:myws top-ns:com.my.company branch:master

  Creates a component.

  poly create component name:NAME [interface:INTERFACE] [:git-add]

    NAME = The name of the component to create.

    :git-add = If :vcs > :auto-add in workspace.edn is set to false,
               then we can pass in this flag instead, to explicitly add the
               created files to git.

    INTERFACE = The name of the interface (namespace) or NAME if not given.

  Example:
    poly create c name:user
    poly create component name:user
    poly create component name:user :git-add
    poly create component name:admin interface:user

  Creates a base.

  poly create base name:NAME [:git-add]

    NAME = The name of the base to create.

    :git-add = If :vcs > :auto-add in workspace.edn is set to false,
               then we can pass in this flag instead, to explicitly add the
               created files to git.

  Example:
    poly create b name:mybase
    poly create base name:mybase
    poly create base name:mybase :git-add

  Creates a project.

  poly create project name:NAME [:git-add]
    NAME = The name of the project to create.

    :git-add = If :vcs > :auto-add in workspace.edn is set to false,
               then we can pass in this flag instead, to explicitly add the
               created files to git.

  Example:
    poly create p name:myproject
    poly create project name:myproject
    poly create project name:myproject :git-add

  Creates a workspace in current directory. If the workspace is created within
  an existing git repo, then that repository will be used. If the workspace is
  created outside a git repo, then you have two alternatives:

  1. Pass in :commit and let the tool initiate the repository and commit the files
     for you, using these commands:
       git init
       git add .
       git commit -m "Workspace created."

  2. Initiate the workspace manually by executing commands similar to the ones above.

  poly create workspace [name:NAME] top-ns:TOP-NAMESPACE [:commit] [branch:BRANCH]

    NAME = The name of the workspace to create, which must be given
           if created outside a git repository. Otherwise it's optional.

    TOP-NAMESPACE = The top namespace name.

    BRANCH = The name of the branch, or main if not given.

  Example:
    poly create w name:myws top-ns:com.my.company :commit
    poly create workspace name:myws top-ns:com.my.company
    poly create workspace name:myws top-ns:com.my.company :commit
    poly create workspace name:myws top-ns:com.my.company branch:master :commit

  Shows dependencies.

  poly deps [project:PROJECT] [brick:BRICK] [out:FILENAME]

    (omitted) = Shows workspace dependencies.

    PROJECT = Shows dependencies for the given project.

    BRICK = Shows dependencies for the given brick.

    FILENAME = The name of the text file to create, containing the
               output from this command.

  To get help for a specific diagram, type:
    poly help deps ARGS:

      ARGS = :brick           Help for the brick diagram.
             :project         Help for the project diagram.
             :project :brick  Help for the project/brick diagram.
             :workspace       Help for the workspace diagram.

  Example:
    poly deps
    poly deps brick:mybrick
    poly deps project:myproject
    poly deps project:myproject brick:mybrick
    poly deps out:deps.txt

  Shows dependencies for selected brick.

  poly deps brick:BRICK [out:FILENAME]

    BRICK = The name of the brick to show dependencies for.

    FILENAME = The name of the text file to create, containing the
               output from this command.

  used by  <  user  >  uses
  -------              ----
  payer                util

  In this example, user is used by payer and it uses util itself.
  If a brick or interface ends with '(t)' then it indicatest that
  it's only used from the test context.

  Example:
    poly deps brick:mybrick
    poly deps brick:mybrick out:deps.txt

  Shows dependencies for selected project.

  poly deps project:PROJECT [out:FILENAME]

    PROJECT = The project name or alias to show dependencies for.

    FILENAME = The name of the text file to create, containing the
               output from this command.

         p
         a  u  u
         y  s  t
         e  e  i
  brick  r  r  l
  --------------
  payer  .  x  t
  user   .  .  x
  util   .  .  .
  cli    x  +  +

  When the project is known, we also know which components are used.

  In this example, payer uses user in the src context, and util only
  in the test context. user uses util, and cli uses payer. The 't'
  means that payer is only used in the test context by user. The +
  signs mark indirect dependencies, while - signs (not present here)
  mark indirect dependencies in the test context. Here the cli base
  depends on user and util, via 'cli > payer > user' and
  'cli > payer > util'. Each usage comes from at least one :require
  statement in the brick.

  Example:
    poly deps project:myproject
    poly deps project:myproject out:deps.txt

  Shows dependencies for the workspace.

  poly deps [:swap-axes] [out:FILENAME]

    :swap-axes = Swaps the diagram's x and y axes.

    FILENAME   = The name of the text file to create, containing the
                 output from this command.

         p
         a  u  u
         y  s  t
         e  e  i
  brick  r  r  l
  --------------
  payer  .  x  t
  user   .  .  x
  util   .  .  .
  cli    x  .  .

  In this example, payer uses user from the src context, and util from
  the test context (indicated by 't'). user uses util and cli uses payer.
  Each usage comes from at least one :require statement in the brick.

  Example:
    poly deps
    poly deps :swap-axes
    poly deps out:deps.txt

  Shows dependencies for selected brick and project.

  poly deps project:PROJECT brick:BRICK [out:FILENAME]

    PROJECT = The project (name or alias) to show dependencies for.

    BRICK = The brick to show dependencies for.

    FILENAME = The name of the text file to create, containing the
               output from this command.

  used by  <  user  >  uses
  -------              ----
  payer                util

  In this example, user is used by payer and it uses util itself.
  If a brick ends with '(t)' then it indicatest that it's only used
  from the test context.

  Example:
    poly deps project:myproject brick:mybrick
    poly deps project:myproject brick:mybrick out:deps.txt

  Shows changed files since the most recent stable point in time.

  poly diff [since:SINCE]

  If since:SINCE is passed in as an argument, the last stable point in time will be
  used depending on the value of SINCE (or the first commit if no match was found).

  If prefixed with 'previous-', e.g. 'previous-release', then the SHA directly before
  the most recent matching tag of the 'release' pattern will be used:
    stable  -> the latest tag that matches stable-*, defined by
               :tag-patterns > :stable in workspace.edn.
    release -> the latest tag that matches v[0-9]*, defined by
               :tag-patterns > :release in workspace.edn.
    KEY     -> any key in :tag-patterns.
    SHA     -> a git SHA-1 hash (if no key was found in :tag-patterns).

  Internally, it executes 'git diff SHA --name-only' where SHA is the SHA-1
  of the first commit in the repository, or the SHA-1 of the most recent tag
  that matches the default pattern 'stable-*' or the passed in since:SINCE.

  Stable points are normally set by the CI server or by individual developers,
  e.g. Lisa, with 'git tag -f stable-lisa'.

  The pattern can be changed in :tag-patterns in workspace.edn.

  The way the latest tag is found is by taking the first line that matches the
  'stable-*' regular expression, or if no match was found, the first commit in
  the repository:
    git log --pretty=format:'%H %d'

  Here is a compact way of listing all the commits including tags:
    git log --pretty=oneline

  Example:
    poly diff
    poly diff since:65a7918
    poly diff since:head
    poly diff since:head~1
    poly diff since:stable
    poly diff since:release
    poly diff since:previous-release

  Opens a help page in a web browser.

  poly doc [ARG]

    ARG = (omitted)    -> Opens the poly tool readme (first page).

          help:COMMAND -> Opens the help for the given poly COMMAND,
                          or the overall help if not given.

          page:PAGE    -> Opens the given PAGE of the poly tool documentation.

          ws:KEY       -> Opens the workspace structure section of the poly tool
                          documentation, and scrolls to the KEY section.

          more:TYPE    -> Opens the given blog-post, podcast, video, et cetera.

  Example:
    poly doc
    poly doc help
    poly doc help:check
    poly doc page:install
    poly doc ws:settings
    poly doc more:blog-posts
    poly doc more:blog-posts:how-polylith-came-to-life
    poly doc more:high-level
    poly doc more:high-level:who-made-this
    poly doc more:podcasts
    poly doc more:podcasts:polylith-with-joakim-james-and-furkan
    poly doc more:python-tool
    poly doc more:slack
    poly doc more:videos
    poly doc more:videos:polylith-in-a-nutshell
    poly doc more:workspaces:realworld

  Shows workspace information.

  poly info [:loc] [out:FILENAME]

    :loc     = Shows the number of lines of code for each brick and project.

    FILENAME = The name of the text file to create, containing the output from
               this command.

  All the arguments used by the 'test' command can also be used as a way to see
  what tests will be executed.

    stable since: dec73ec | stable-lisa

    projects: 2   interfaces: 3
    bases:    1   components: 4

    active profiles: default

    project       alias  status   dev  admin
    ---------------------------   ----------
    command-line  cl      ---     ---   --
    development   dev     s--     s--   --

    interface  brick    cl    dev  admin
    -----------------   ---   ----------
    payer      payer    s--   st-   --
    user       admin    s--   ---   s-
    user       user *   ---   st-   --
    util       util     s--   st-   --
    -          cli      s--   st-   --

  This example shows a sample workspace. Let's go through each section:

  1. stable since: dec73ec | stable-lisa

     Shows the most recent commit marked as stable, or the last release if
     since:release or since:previous-release was given, or the first commit
     in the repository if no tag was found, followed by the tag (if found).
     More information can be found in the 'diff' command help.

  2. projects: 2   interfaces: 3
     bases:    1   components: 4

     Shows how many projects, bases, components and interfaces there are
     in the workspace.

  3. active profiles: default

     Shows the names of active profiles. The profile paths are merged into the
     development project. A profiles is an alias in ./deps.edn that starts
     with a +. If no profile is selected, the default profile is automatically
     selected.

     Profiles are activated by passing them in by name (prefixed with '+'), e.g.:
       poly info +admin +onemore

     To deactivate all the profiles, and stop 'default' from being merged into
     the development project, type:
       poly info +

  4. project       alias  status   dev  admin
     ---------------------------   ----------
     command-line  cl      ---     ---   --
     development   dev     s--     s--   --

    This table lists all projects. The 'project' column shows the name
    of the projects, which are the directory names under the 'projects',
    directory except for 'development' that stores its code under the
    'development' directory. If any file within the project directory has
    changed, then it will be marked with a *. If that's not the case, but
    any of the included bricks are changed, then it will be marked with a +.

    The 'deps.edn' config files are stored under each project, except for
    the development project that stores it at the workspace root.

    Aliases are configured in :projects in ./workspace.edn.

    The 'status' column has three flags with different meaning:
      s--  The project has a 'src' directory, e.g.
           'projects/command-line/src'.
      -t-  The project has a 'test' directory, e.g.
           'projects/command-line/test'.
      --x  The project tests (its own) are marked for execution.

    To show the 'resources' directory, also pass in :r or :resources, e.g.
    'poly info :resources':
      s---  The project has a 'src' directory, e.g.
            'projects/command-line/src'.
      -r--  The project has a 'resources' directory, e.g.
            'projects/command-line/resources'.
      --t-  The project has a 'test' directory, e.g.
            'projects/command-line/test'
      ---x  The project tests (its own) are marked for execution.

    The dev column has three flags with different meaning:
      s--  The project's 'src' directory, e.g.
           'development/src' is added to './deps.edn'
      -t-  The project's 'test' directory, e.g.
           'development/test' is added to './deps.edn'
      --x  The project tests are marked for execution from development.

    The last admin column, is a profile:
      s-  The profile contains a path to the 'src' directory, e.g.
          'projects/command-line/src'.
      -t  The profile contains a path to the 'test' directory, e.g.
          'projects/command-line/test'.

    If also passing in :r or :resources, e.g. 'poly info :resources':
      s--  The profile contains a path to the 'src' directory, e.g.
           'projects/command-line/src'.
      -r-  The profile contains a path to the 'resources' directory, e.g.
           'projects/command-line/resources'.
      --t  The profile contains a path to the 'test' directory, e.g.
           'projects/command-line/test'.

  5. interface  brick    cl    dev  admin
     -----------------   ---   ----------
     payer      payer    s--   st-   --
     user       admin    s--   ---   st
     user       user *   ---   st-   --
     util       util     s--   st-   --
     -          cli      s--   st-   --

    This table lists all bricks and in which projects and profiles they are
    added to.

    The 'interface' column shows what interface the component has. The name
    is the first namespace after the top namespace, e.g.:
    com.my.company.user.interface

    The 'brick' column shows the name of the brick, in green if a component or
    blue if a base. Each component lives in a directory under the 'components'
    directory and each base lives under the 'bases' directory. If any file for
    a brick has changed since the last stable point in time, it will be marked
    with an asterisk, * (user in this example).

    The changed files can be listed by executing 'poly diff'.

    The next cl column is the command-line project that lives under the
    'projects' directory. Each line in this column says whether a brick is
    included in the project or not.
    The flags mean:
      s--  The project contains a path to the 'src' directory, e.g.
           'components/user/src' (or is indirectly added by a :local/root).
      -t-  The project contains a path to the 'test' directory, e.g.
           'components/user/test' (or is indirectly added by a :local/root).
      --x  The brick is marked to be executed from this project.

    If :r or :resources is also passed in:
      s---  The project contains a path to the 'src' directory, e.g.
            'components/user/src' (or is indirectly added by a :local/root).
      -r--  The project contains a path to the 'resources' directory, e.g.
            'components/user/resources' (or is indirectly added by a :local/root).
      --t-  The project contains a path to the 'test' directory, e.g.
            'components/user/test' (or is indirectly added by a :local/root).
      ---x  The brick is marked to be executed from this project.

    The next group of columns, dev admin, is the development project with
    its profiles. If passing in a plus with 'poly info +' then it will also show
    the default profile. The flags for the dev project works the same
    as for cl.

    The flags for the admin profile means:
      s-  The profile contains a path to the 'src' directory, e.g.
          'components/user/src'.
      -t  The profile contains a path to the 'test' directory, e.g.
          'components/user/test'

  It's not enough that a path has been added to a project to show an 'x',
  the file or directory must also exist.

  If any warnings or errors were found in the workspace, they will be listed at
  the end, see the 'check' command help, for a complete list of validations.

  Example:
    poly info
    poly info :loc
    poly info since:release
    poly info since:previous-release
    poly info project:myproject
    poly info project:myproject:another-project
    poly info brick:mycomponent
    poly info brick:mycomponent:mybase
    poly info color-mode:none
    poly info :project
    poly info :dev
    poly info :project :dev
    poly info :all
    poly info :all-bricks
    poly info out:info.txt
    poly info ws-dir:another-ws
    poly info ws-file:ws.edn

  Shows all libraries that are used in the workspace.

  poly libs [:compact] [:outdated] [:update] [libraries:LIBS] [out:FILENAME]

    :compact  = Shows the table in a more compact way.

    :outdated = Shows the latest version of each library, or blank if up to date.

    :update   = Updates all libraries to the latest version. If LIBS is given,
                then only update selected libraries.
                Old library versions can be kept by giving the library as a symbol in
                :keep-lib-versions for bricks and projects in workspace.edn.

    FILENAME  = The name of the text file to create, containing the
                output from this command.
                                                                                 u  u
                                                                                 s  t
                                                                                 e  i
    library                 version    type      KB   cl   dev  default  admin   r  l
    -----------------------------------------------   --   -------------------   ----
    antlr/antlr             2.7.7      maven    434   x     x      -       -     .  x
    clj-time                0.15.2     maven     23   x     x      -       -     x  .
    org.clojure/clojure     1.10.1     maven  3,816   x     x      -       -     .  .
    org.clojure/tools.deps  0.16.1264  maven     46   x     x      -       -     .  .

  In this example we have four libraries used by the cl and dev projects.
  If any of the libraries are added to the default or admin profiles, they will appear
  as an x in these columns. Remember that src and test sources live together in a
  profile, which is fine because they are only used from the development project.

  The x for the cl and dev columns says that the library is part of the src scope.
  If a library is only used from the test scope, then it's marked with a 't'.
  A library used in the test scope, can either be specified directly by the project
  itself via :aliases > :test > :extra-deps or indirectly via included bricks in
  :deps > :local/root which will be picked up and used by the 'test' command.

  The x in the user column, tells that clj-time is used by that component
  by having it specified in its 'deps.edn' file as a src dependency.
  If a dependency is only used from the test scope, then it will turn up as a t.

  Libraries can also be selected per project and it's therefore possible to have
  different versions of the same library in different projects (if needed).
  Use the :override-deps key in the project's 'deps.edn' file to explicitly set
  a version for one or several libraries in a project.

  The 'type' column says in what way the dependency is included, e.g.:
   - maven: clj-time/clj-time {:mvn/version "0.15.2"}
   - local: clj-time {:local/root "/local-libs/clj-time-0.15.2.jar"}
   - git:   clj-time/clj-time {:git/url "https://github.com/clj-time/clj-time.git"
                               :sha     "d9ed4e46c6b42271af69daa1d07a6da2df455fab"}

  The KB column shows the size in kilobytes, which is the size of the jar
  file for Maven and Local dependencies, and the size of all files in the
  ~/.gitlibs/libs/YOUR-LIBRARY directory for Git dependencies.

  Example:
    poly libs
    poly libs :compact
    poly libs :outdated
    poly libs :update
    poly libs :update libraries:metosin/malli:zprint/zprint
    poly libs out:libs.txt
    poly doc page:libraries

  Migrates a workspace to the latest version.

  poly migrate

  If the workspace hasn't been migrated already, then this command will create a new
  ./workspace.edn file + a deps.edn file per brick. All project deps.edn files will be
  updated. The libraries in each project's deps.edn file will be sorted, so it can be
  an idea to manually change that order and put bricks first followed by the
  libraries.

  The migration tool will use the :ns-to-lib key to figure out what libraries are
  used in each brick. After the migration, it's recommended to go through all the
  bricks and make sure that all libraries it uses are also specified in each brick's
  deps.edn file.

  Continue by updating each project's deps.edn file and remove libraries that are
  already indirectly included by bricks (via :local/root).
  The paths in ./deps.edn is left untouched and the reason is that the :local/root
  syntax is not supported by all IDE's.

  Starting from version 0.2.0-alpha10, the tool supports specifying dependencies per
  brick in its own deps.edn files. Workspace specific config is stored in
  ./workspace.edn instead of the :polylith key in ./deps which was the case prior to
  this version.

  Shows the output from the info, deps, and libs commands, side by side.
  This command is mainly used to generate an image for our documentation
  and is only available from the polyx tool.

  We can duplicate the :poly alias in ./deps.edn and rename it to :polyx and
  change :deps/root to "projects/polyx" to get access to the :polyx command.

  poly overview [:no-changes] [out:FILENAME]

    (omitted)  = Shows the output.

    :no-changes = Shows the output as if there were no changes in the workspace.

    FILENAME = Creates a text or image file based on the output.
               If FILENAME ends with .txt, then the file will contain
               the output as text. If FILENAME ends with .bmp, .wbmp, .gif,
               .png, .jpeg, .jpg, .png, .tif, or .tiff, then the file will be
               generated as an image.

  Example:
    clojure -M:polyx overview
    clojure -M:polyx overview out:overview.png
    clojure -M:polyx overview out:overview.jpg :no-changes

  Starts an interactive shell with the name of the selected workspace, e.g.:
    myworkspace$>

  poly [shell] [:all] [:tap]

    :all = The autocomplete will suggest all available arguments,
           including rarely used ones.

    :tap = A Portal window that outputs tap> statements is opened.

  From here we can execute any poly command, e.g.:
    myworkspace$> info

  We can also use the built in autocomplete, e.g.:
    myworkspace$> i

  ...and when pressing the <tab> key, the 'i' is completed to 'info'.

  This works for both commands and arguments, and is context sensitive.
  If we for example type:
    myworkspace$> deps brick:mybrick project:

  ...and press <tab>, it will only suggest projects that include 'mybrick'.

  Arguments that start with a : can be selected by just typing their name,
  e.g. 'l' will select ':loc'. To distinguish between 'project:PROJECT' and
  ':project' we need to type ':p' to select ':project'.

  From the shell we also have access to these commands:
    switch-ws ARG  Switches to selected workspace.
    tap [ARG]      Opens (or closes/cleans) a portal window that outputs tap>
                   statements.
    exit           Exits the shell.
    quit           Quits the shell.

  It's also possible to start a shell and switch to a workspace at the same time,
  e.g.:
    poly shell ws-dir:examples/doc-example
    poly shell ws-file:realworld.edn

  An alternative way of exiting the shell is by pressing <ctrl>+C or <ctrl>+D.

  Example:
    poly shell
    poly shell :all
    poly shell :tap
    poly shell :all :tap
    poly doc page:shell

  Selects which workspace to be used by commands executed from the shell.
  After we have switched workspace, all subsequent commands will append either
  ws-dir:DIR or ws-file:FILE, depending on whether we switch to a directory or a file.

  switch-ws [dir:DIR] [file:FILE]

    DIR = Switches to the given workspace directory.
          The prompt will be prefixed with 'dir:' to show this.

    FILE = Switches to the workspace specified in the selected file,
           created by something like 'poly ws out:ws.edn'.
           The prompt will be prefixed with 'file:' to show this.

  Example:
    switch-ws dir:~/myworkspace
    switch-ws file:../../another/ws.edn

  Opens (or closes/cleans) a portal window (https://github.com/djblue/portal)
  where tap> statements are sent to. This command is used from the shell and
  is mainly used internally when developing the poly tool itself.

  tap [ARG]

    ARG = (omitted)  Opens a portal window.
          open       Opens a portal window.
          close      Closes the portal window
          clear      Clears the portal window

  Example:
    tap
    tap open
    tap clean
    tap close
    doc page:tap

  Executes brick and/or project tests.

  poly test [ARGS]

  The brick tests are executed from all projects they belong to except for the
  development project (if not :dev is passed in):

  ARGS              Tests to execute
  ----------------  -------------------------------------------------------------
  (omitted)         All brick tests that are directly or indirectly changed.

  :project          All brick tests that are directly or indirectly changed +
                    tests for changed projects.

  :all-bricks       All brick tests.

  :all              All brick tests + all project tests (except development).


  To also execute the brick tests from the development project, pass in :dev:

  ARGS              Tests to execute
  ----------------  -------------------------------------------------------------
  :dev              All brick tests that are directly or indirectly changed,
                    executed from all projects (development included).

  :project :dev     All brick tests that are directly or indirectly changed,
                    executed from all projects (development included) +
                    tests for changed projects (development included).

  :all-bricks :dev  All brick tests, executed from all projects
                    (development included).

  :all :dev         All brick tests, executed from all projects
                    (development included) + all project tests
                    (development included).

  Projects can also be explicitly selected with e.g. project:proj1 or
  project:proj1:proj2.

  We can also specify which bricks to include, by listing them like this:
  brick:mycomponent:another-component:mybase

  Example:
    poly test
    poly test :project
    poly test :all-bricks
    poly test :all
    poly test project:proj1
    poly test project:proj1:proj2
    poly test brick:mycomponent
    poly test brick:mycomponent:mybase
    poly test :dev
    poly test :project :dev
    poly test :all-bricks :dev
    poly test :all :dev
    poly doc page:testing
    poly doc page:test-runners

  poly version

  Prints out:
    - the tool name ('poly' or 'polyx')
    - the version (major.minor.patch)
    - the revision (SNAPSHOT if a shapshot release, otherwise empty)
    - snapshot sequence number (if a snapshot release)
    - the date (year-month-day)

  Example of a final release:
    poly 0.2.18 (2023-09-27)

  Example of a snapshot release:
    poly 0.2.18-SNAPSHOT #1 (2023-09-15)

  The poly tool does not only version control releases but also the public API,
  the workspace structure, and the test runner API, which we can read more about
  by executing:
    poly doc ws:version

  Prints or writes the workspace as data.

  poly ws [get:ARG] [out:FILE] [branch:BRANCH] [:latest-sha]

    ARG = keys  -> Lists the keys for the data structure:
                   - If it's a hash map, it returns all its keys.
                   - If it's a list and its elements are hash maps,
                     it returns a vector with all the :name keys.

          count -> Counts the number of elements.

          KEY   -> If applied to a hash map, it returns the value of the KEY.
                   If applied to a list of hash maps, it returns the hash map with
                   a matching :name. Projects are also matched against :alias
                   e.g. 'dev' instead of 'development'.

          INDEX -> A list element can be looked up by INDEX.

          Several ARG keys can be given, separated by colon.
          Every new key goes one level deeper into the workspace data structure.

    FILE = Writes the output to the specified FILE. Will have the same effect
           as setting color-mode:none and piping the output to a file.

    BRANCH = Can be used together with :latest-sh to set the branch to use
             if other than 'main'.

    :latest-sha = if passed in, then settings:vcs:polylith:latest-sha will be set,
                  by retreiving the latest sha from the 'main' branch.
  Example:
    poly ws
    poly ws get:keys
    poly ws get:count
    poly ws get:settings
    poly ws get:user-input:args
    poly ws get:user-input:args:0
    poly ws get:settings:keys
    poly ws get:components:keys
    poly ws get:components:count
    poly ws get:components:mycomp:lines-of-code
    poly ws get:settings:vcs:polylith :latest-sha
    poly ws get:settings:vcs:polylith :latest-sha branch:master
    poly ws out:ws.edn
    poly ws color-mode:none > ws.edn
    poly doc ws
    poly doc ws:components