Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rivy/deno.dxx

:rocket: (Deno) enhanced executor
https://github.com/rivy/deno.dxx

cli deno

Last synced: 28 days ago
JSON representation

:rocket: (Deno) enhanced executor

Awesome Lists containing this project

README 

        



# 🦕 Enhanced Deno commands



## `dxf`, `dxi`, `dxr`, and `dxx`



Fixes...



- ref: [🙏(feat/req) supply $0/%0 to shimmed scripts (cross-platform)](https://github.com/denoland/deno/issues/9874)

- ref: [🙏(feat/req) suppress annoying "Terminate batch job (Y/N)?" for shimmed deno scripts (Windows)](https://github.com/denoland/deno/issues/9873)

- ref: [🐛(or feat request?) CLI apps need original command line (Windows)](https://github.com/denoland/deno/issues/9871)

- ref: [🐛`deno` v1.13 breaks shims using `--allow-plugin`](https://github.com/denoland/deno/issues/11819)



### formatter (`dxf`)



automatically runs `dprint fmt` if `dprint` is available and a config is found in the main repo directory o/w runs `deno fmt`



### installer (`dxi`)



- installs command scripts with an enhanced shim



  - command line expansion enhancement

    - enables automated, bash-like command line expansion (including full brace and advanced glob expansion) for WinOS platforms; pass-through for non-Windows platforms

    - when using the 'xProcess' library, enables scripts to more accurately determine the their invocation text allowing them to show accurate help and examples

  - blocks the annoying "Terminate batch job (Y/N)?" console question when using CTRL-C to interrupt the script

    - the visible "^C^C" can likely be removed as well with raw input and/or signal handling (see feat/req @ )



- [WIP] can revise current shims, adding enhanced-shim functionality

  - prototypes for shim revision are contained in the 'tools' directory



### runner (`dxr`)



- runs scripts with the same command line expansion enhancements as `dxi`



- [WIP]

  - automatically run dexter / XTR files

  - automatically set requested permissions

    - warn when setting without a CLI specification

  - can run distant scripts from the command line

    - like `dpx` but also searches within additional directories ('src', ...)

    - can also install the remote script with an '--install' flag



### integrator (`dxx`)



- [WIP]



## dexter / xtr



- [WIP]



## Installation of Tools



> Note: project is using [email protected] which requires Deno v1.20.5 or greater.



```shell

# `dxi`

deno install -A "https://deno.land/x/[email protected]/src/dxi.ts"

#

dxi -A "https://deno.land/x/[email protected]/src/dxf.ts"

dxi -A "https://deno.land/x/[email protected]/src/dxr.ts"

# WIP: dxi .../dxx

#...or (via CDN, with optional version/version-range/latest/commit support)...

# dxi -A "https://cdn.jsdelivr.net/gh/rivy/[email protected]/src/dxf.ts" // v0.0.16

# dxi -A "https://cdn.jsdelivr.net/gh/rivy/deno.dxx@COMMIT/src/dxf.ts"  // commit

```



## Using the 'xProcess' library



Solely using `dxr` (after installation with `dxi`) as a script runner will perform _bash-like argument expansion_ for the target script while _preserving correct quote semantics_ for both double and single quoted arguments. Additional functionality requires use of the 'xProcess' library in coordination with either an enhanced runner, such as `dxr`, an enhanced shim (provided by installation with `dxi`), or using FFI (currently [as of 2022-01-01] requiring the use of `--unstable`).



Comparisons of `eg\args.ts` (using 'xProcess') vs `args-naive.ts` (without 'xProcess', using only `deno` built-ins) in various scenarios...



```shell

C:> ::# `deno`-only support => no expansion and uneven quote support with loss of quote context

C:> deno run -A eg/args-naive.ts '*' * "*"

'*' * *



C:> ::# `deno` for scripts using 'xProcess' => bash-like expansion, but broken preservation of quoted arguments

C:> deno run -A eg/args.ts '*' * "*"

* bench CHANGELOG.mkd eg LICENSE README.md src tests tools tsconfig.json VERSION bench CHANGELOG.mkd eg LICENSE README.md src tests tools tsconfig.json VERSION



C:> ::# `dxr` => bash-like expansion with preservation of quoted arguments

C:> dxr eg/args-naive.ts '*' * "*"

* bench CHANGELOG.mkd eg LICENSE README.md src tests tools tsconfig.json VERSION *



C:> ::# `dxr` => bash-like expansion with preservation of quoted arguments; better `$0` functionality available

C:> dxr eg/args.ts '*' * "*"

* bench CHANGELOG.mkd eg LICENSE README.md src tests tools tsconfig.json VERSION *

```



Fully capable, completely self-contained, executable binaries can be built from scripts which use the 'xProcess' library by compiling them with the `--allow-all` and `--unstable` flags. For example, using `deno compile -A --unstable eg/args.ts` (from the main project directory, on the WinOS platform) will produce a binary `args.exe` which contains all the enhanced argument functionality and requires no extra support. The resultant `args.exe` binary may be moved to any other WinOS platform and executed with full fidelity.



## Development



### Tools



- [`bmp`](https://deno.land/x/[email protected]) (v0.0.7+) ... synchronizes version strings within the project

  - install using `dxi --allow-read=. --allow-write=. --allow-run=git -f https://deno.land/x/[email protected]/cli.ts`

- [`git-changelog`](https://github.com/rivy-go/git-changelog) (v1.1+) ... enables changelog automation

  - install using `go get -u github.com/rivy-go/git-changelog/cmd/git-changelog`



### Maintenance



#### CHANGELOG



`git changelog > CHANGELOG.mkd`



#### Version



- `bmp` ~ check project for synchronized version strings

- `bmp --commit --[major|minor|patch]` ~ update project version strings



### Version update process



```shell

bmp --[major|minor|patch]

git changelog --next-tag v$(cat VERSION) > CHANGELOG.mkd

bmp --commit

```



## Testing



> Optional testing tools

>

> - [`bmp`](https://deno.land/x/[email protected]) 
 `dxi --allow-read=. --allow-write=. --allow-run=git -f https://deno.land/x/[email protected]/cli.ts`

> - [`commitlint`](https://www.npmjs.com/package/@commitlint/cli) 
 `npm install --global @commitlint/cli@17 @commitlint/config-conventional@17`

> - [`cspell`](https://www.npmjs.com/package/cspell) 
 `npm install --global cspell@5`

> - [`madge`](https://www.npmjs.com/package/madge) 
 `npm install --global madge@6`



Use `deno test -A`.



> For `deno test -A -- --test-xxx` or `deno test -A -- --xxx`, testing scripts may use `import { setEnvFromArgs } from './$shared.permit.ts'; setEnvFromArgs(Deno.args);` which will set the environment variable `TEST_XXX` to 'true' during testing.



### distribution release testing



Use `deno test -A -- --release` (or `--test-dist`, `--test-release`) to enable and perform full release testing prior to distribution of a release.



## Coverage Reports



```shell

rm .coverage

deno test -A --coverage=.coverage

deno coverage --lcov --exclude="test[.](js|mls|ts|jsx|tsx)$" --exclude="tests/**" .coverage | perl -pe "use Cwd; $cwd = (getcwd() =~ s/[\\\/]/[\\\\\\\/]/gmrsu); s/^SF:${cwd}\\/SF:/gmsu;" > .coverage/@coverage.lcov

genhtml -o .coverage\html .coverage\@coverage.lcov

# for WinOS => start "" .coverage\html\index.html

```



## Benchmarking



`dxr bench/bench-parser.ts`



## Publishing



### Pre-publishing



```shell

#=== * POSIX

# update project VERSION strings (package.json,...)

# * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format

bmp --patch

VERSION=$(cat VERSION)

git-changelog --next-tag "v${VERSION}" > CHANGELOG.mkd

# create/commit updates and distribution

git add .bmp.yml CHANGELOG.mkd README.md VERSION .

git commit -m "${VERSION}"

git reset --hard && git clean -fdx && git submodule foreach "git reset --hard ; git clean -fdx" ## aka `git realclean`

# tag VERSION commit

git tag -f "v${VERSION}"

# (optional) prerelease checkup

deno test -A -- --release

```



```shell

@rem #=== * WinOS

@rem # update project VERSION strings (package.json,...)

@rem # * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format

bmp --patch

for /f %G in (VERSION) do @set "VERSION=%G"

git-changelog --next-tag "v%VERSION%" > CHANGELOG.mkd

@rem # create/commit updates and distribution

git add .bmp.yml CHANGELOG.mkd README.md VERSION .

git commit -m "%VERSION%"

git reset --hard && git clean -fdx && git submodule foreach "git reset --hard ; git clean -fdx" &@rem ## aka `git realclean`

@rem # tag VERSION commit

git tag -f "v%VERSION%"

@rem # (optional) prerelease checkup

deno test -A -- --release

```



### Publish



```shell

deno test -A -- --release # expect exit code == 0

# * optional (will be done in 'prePublishOnly' by `npm publish`)

git reset --hard && git clean -fdx && git submodule foreach "git reset --hard ; git clean -fdx" ## aka `git realclean`

git-changelog > CHANGELOG.mkd # expect exit code == 0

git diff-index --quiet HEAD || echo "[lint] ERROR uncommitted changes" # expect no output and exit code == 0

# * push to deno.land with tag push

git push local --tags

```