feat(package): list packages

[line-o]

closes #7

xst package list [options]

List installed packages

Options:
      --version               Show version number                                          [boolean]
      --config                configuration to use
      --help                  Show help                                                    [boolean]
  -G, --color                 Color the output                            [boolean] [default: false]
  -V, --versions              Display installed version                   [boolean] [default: false]
  -e, --extended              Display more information for each item      [boolean] [default: false]
  -t, --typesort              Sort by type                                [boolean] [default: false]
  -T, --timesort              Sort by installation date                   [boolean] [default: false]
  -r, --reverse               Reverse the order of the sort                                [boolean]
  -a, --app, --applications   Only list installed application packages                     [boolean]
  -l, --lib, --libraries      Only list installed library packages                         [boolean]
      --date                  Show installation date                       [choices: "short", "iso"]
  -D, --deps, --dependencies  Show package dependencies                   [boolean] [default: false]
      --full-name             Use full name for packages and dependencies [boolean] [default: false]
      --raw                   Return raw JSON data from query             [boolean] [default: false]

Implements all options in #7 and then some. Except the ability to filter the list using a globbing expression. This should rather be done as a separate command xst package info <package-abbrev>.

[line-o]

example output of the templating library with --extended

templating
Title: eXist-db HTML Templating Library
URI: http://exist-db.org/html-templating
Author: eXist-db Project
Description: This package contains the HTML templating library for eXist, which was previously part of the now deprecated 'shared-resources'
Website: https://github.com/eXist-db/templating
Version: 1.1.0
Installed: 2023-01-04T17:05:21.129+01:00
Processor: existdb >=5.2.0
Type: library
License: LGPL-2.1
Components:
  xquery:
    http://exist-db.org/xquery/html-templating
    http://exist-db.org/xquery/html-templating/lib

[line-o]

Example output of xst package list --app --versions --dependencies

dashboard           2.0.9
├── functx >=1.0
└── packageservice >=1.3.8
eXide               3.4.0
└── (no dependency)
exist-documentation 5.4.0
└── templating >=1.0.2
fundocs             1.2.0
└── templating >=1.0.2
monex               3.0.5
└── templating >=1.0.2
packageservice      1.3.14
├── functx *
└── semver-xq *

With --dependencies each dependency will be checked to be installed and version mismatches detected. Example output for exist-documentation when the templating module is not installed:

exist-documentation 5.4.0
└── ! http://exist-db.org/html-templating >=1.0.2

[line-o]

Example --extended output for functx

functx
Title: FunctX library
Name: http://www.functx.com
Author: Priscilla Walmsley
Description: The FunctX XQuery/XSLT 2.0 function library is a set of reusable functions for XQuery 1.0 and XSLT 2.0. The project itself is an open source application and framework for developers to create function libraries.
Website: http://www.functx.com/
Version: 1.0.1
Installed: 2023-01-06T21:41:14.261+01:00
Processor: any
Type: library
License: GNU-LGPL
Components:
  xslt: http://www.functx.com/functx.xsl
  xquery: http://www.functx.com

[line-o]

--raw can be used to pipe the json result to jq

xst package list --raw | jq '.packages[0]' -M

{
  "date": "2023-01-04T17:05:22.989+01:00",
  "processor": {
    "name": "http://exist-db.org",
    "semverMin": "5.3.0-SNAPSHOT",
    "semverMax": null,
    "semver": null,
    "versions": []
  },
  "components": {
    "xslt": [],
    "xquery": [],
    "xproc": [],
    "xsd": [],
    "rng": [],
    "schematron": [],
    "nvdl": [],
    "resource": [],
    "jar": []
  },
  "website": "https://www.github.com/exist-db/documentation",
  "abbrev": "fundocs",
  "target": "fundocs",
  "description": null,
  "type": "application",
  "name": "http://exist-db.org/apps/fundocs",
  "authors": [
    "eXist-db"
  ],
  "version": "1.2.0",
  "title": "XQuery Function Documentation",
  "dependencies": [
    {
      "name": "http://exist-db.org/html-templating",
      "semverMin": "1.0.2",
      "semverMax": null,
      "semver": null,
      "versions": []
    }
  ],
  "license": "GNU Lesser General Public License, version 2.1"
}

[joewiz]

In this raw output, "template" is again a bit misleading. Best to call the properties what they are in the spec: semver-min, semver-max, semver, versions, and name.

[joewiz]

URI: also doesn't conform to the spec. The property is @name, not @uri. In public-repo, we use "Name (URI)" to distinguish the @name property from the package's <title>. I'd suggest either Name: or Name (URI):. (The package spec says the property is an IRI, but in practice I've only ever seen URIs... not to say I can tell you what the difference is without googling.)

[line-o]

I will rename uri to name. I think that is sensible to do as it is in fact a free-text property.

[line-o]

In this raw output, "template" is again a bit misleading. Best to call the properties what they are in the spec: semver-min, semver-max, semver, versions, and name.

I asked about a better name for template above :) Property names in JSON with hyphens are possible, but I would want to avoid them as it makes it less comfortable to work with in JS. It is also somewhat uncommon. We could either

• camelCase them (semverMin, semverMax, semver, versions)
• shorten them (min, max, range, versions)

I do see the value of staying close to the input XML, but it is already aggregated. components.xquery for example combines the information from expath-pkg.xml and exist.xml to show all registered module names in one place.

[line-o]

The property names of dependencies now reflect the attribute names of declared dependencies @joewiz (see updated --raw output).

[line-o]

@joewiz all suggested changes are now implemented. The package itself still had a uri property which is now renamed to name. Also the command line flag --full-uri was renamed to --full-name

[github-actions[bot]]

:tada: This PR is included in version 1.2.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: