diff --git a/.gitattributes b/.gitattributes index 4a94c94c8..ee3ba6fec 100644 --- a/.gitattributes +++ b/.gitattributes @@ -9,3 +9,5 @@ *.mac text eol=lf *.int text eol=lf Dockerfil* text eol=lf +ipm text eol=lf +iriscli text eol=lf diff --git a/CHANGELOG.md b/CHANGELOG.md index 672db1dd2..39b6b8185 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - #992: Implement automatic history purge logic - #973: Enables CORS and JWT configuration for WebApplications in module.xml +- #1110: Add `iriscli` and `ipm` container utility scripts that are auto-installed to `~/.local/bin/` and `~/bin/` so they work both inside and outside of containers (Unix/Linux only) ### Fixed - #1001: The `unmap` and `enable` commands will now only activate CPF merge once after all namespaces have been configured instead after every namespace diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae82f6b40..1ed7872b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,6 +92,49 @@ From time to time, you may also want to remove unused Docker data to save disk s docker system prune -a ``` +#### Convenience Scripts: `ipm` and `iriscli` + +The repo ships two bash scripts that wrap common IRIS interactions so you don't have to type `iris session iris` boilerplate every time. When IPM is installed on Unix/Linux, they are automatically copied to `~/.local/bin/` and `~/bin/` (if it exists), making them available on PATH in most environments including the dev containers. + +**`ipm`** — runs a single IPM/ZPM command non-interactively and exits: +```bash +# List installed packages +docker exec -it ipm list + +# Install a package +docker exec -it ipm install zpm-registry + +# Run tests for a module +docker exec -it ipm test mymodule -only + +# Using docker compose exec (works for any container defined in docker-compose.yml) +# Note: must be run from the directory containing docker-compose.yml +docker compose exec iris ipm list +``` + +**`iriscli`** — opens an interactive IRIS terminal session: +```bash +# Either this command +docker exec -it iriscli + +# Or this equivalent command (must be run from the directory containing docker-compose.yml) +docker compose exec -it iris iriscli +``` + +`iriscli` also accepts an ObjectScript script file, executing each line and then halting: +```bash +docker compose exec -it iris iriscli /path/to/demo.script +``` + +A sample `demo.script`: +```objectscript +zn "USER" +write $zversion,! +zpm "list" +``` + +> **Namespace:** Both scripts respect the `IRIS_NAMESPACE` environment variable, or accept `-U ` as the first argument. For example: `docker exec -it ipm -U %SYS list`. + ### Developing IPM in an Existing IRIS Instance If you already have an IRIS instance running and you want to test IPM in this instance, run the following command: diff --git a/ipm b/ipm new file mode 100644 index 000000000..402cec574 --- /dev/null +++ b/ipm @@ -0,0 +1,73 @@ +#!/bin/bash + +# ipm: convenience wrapper to run an IPM command in an IRIS session +# +# Usage: ipm [-U ] [-i ] +# +# Options: +# -U IRIS namespace to run in (default: USER, or $IRIS_NAMESPACE / $IRISNAMESPACE) +# -i IRIS instance name (default: $ISC_PACKAGE_INSTANCENAME, then "iris") +# -h, --help Show this help message +# +# Examples: +# ipm list # list all installed modules +# ipm install MyModule # install a module from the registry +# ipm test MyModule -only # run tests for a module +# ipm -U USER list # run in a specific namespace +# ipm -i iris list # run against a specific IRIS instance + +# Arrays to accumulate iris session flags and the IPM command tokens +ARGS=() +CMD=() + +# Default instance: prefer the container-standard env var, fall back to "iris" +INSTANCE="${ISC_PACKAGE_INSTANCENAME:-iris}" + +# Seed ARGS with a namespace from the environment if one is set +if [ -n "$IRIS_NAMESPACE" ]; then + ARGS+=( -U "$IRIS_NAMESPACE" ) +elif [ -n "$IRISNAMESPACE" ]; then + ARGS+=( -U "$IRISNAMESPACE" ) +fi + +# Parse command-line arguments +while [[ $# -gt 0 ]]; do + case "$1" in + -h|--help) + # Print the comment block at the top of this file, stripping the leading "# " + sed -n '3,17p' "$0" | sed 's/^# \?//' + exit 0 + ;; + -U) + # Explicit -U overrides any namespace set from the environment + ARGS=( -U "$2" ) + shift 2 + ;; + -i) + INSTANCE="$2" + shift 2 + ;; + *) + # All remaining arguments form the IPM command string + CMD+=( "$1" ) + shift + ;; + esac +done + +if [ ${#CMD[@]} -eq 0 ]; then + echo "Usage: ipm [-U ] [-i ] " >&2 + echo " ipm --help for more information" >&2 + exit 1 +fi + +# Join the CMD array into a single string for the ObjectScript zpm call +CMDSTR="${CMD[*]}" +# Escape any double-quotes in the command string ("" is a literal " in ObjectScript strings) +CMDSTR_ESC=${CMDSTR//\"/\"\"} + +# Pipe the zpm command into iris session; :1:1 flags suppress the session banner and prompt +( + echo "zpm \"${CMDSTR_ESC}\":1:1" + echo "halt" +) | iris session "$INSTANCE" "${ARGS[@]}" diff --git a/iriscli b/iriscli new file mode 100644 index 000000000..b00172143 --- /dev/null +++ b/iriscli @@ -0,0 +1,85 @@ +#!/bin/bash + +# iriscli: convenience wrapper to open an IRIS terminal session or run a script file +# +# Usage: iriscli [-U ] [-i ] [