Restructure to skill-manager conventions

- Move the TypeScript project under scripts/ (src, tsconfig, package.json, pnpm lockfile/workspace, canonical .gitignore); drop the npm package-lock - Add scripts/Taskfile.yml aggregator plus .scripts modules (loggers, base, cli) with build, run, and validate tasks - Move the six SKILL-*.md docs into references/ with kebab names and extract the connector-routing sections from SKILL.md into references/routing-best-practices.md (SKILL.md 666 -> ~310 lines) - Add license/metadata/compatibility frontmatter, an Available scripts section, and update all CLI paths in README and references skill-manager validate: 13/13 passed, 0 warnings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-27 15:20:26 +03:00
parent 99f1fd07e3
commit 77655d1d97
72 changed files with 1089 additions and 1828 deletions
@@ -0,0 +1,11 @@
+# https://taskfile.dev
+
+version: "3"
+
+tasks:
+  environment:show:
+    desc: "Show environment vars"
+    cmds:
+      - |
+        ./.scripts/base/api/environment-show.sh {{ .CLI_ARGS }}
+    silent: true
@@ -0,0 +1,9 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+. ./.scripts/base/lib/--index.sh
+
+_base_environment_show "$@"
@@ -0,0 +1,28 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+export LOCAL_HOME_DIR=$(pwd)
+export LOCAL_HOME_DIR_NAME=${PWD##*/}
+export LOCAL_GIT_ROOT_DIR=$(dirname "${LOCAL_HOME_DIR}")
+
+TMP_BASE_FILE_DOTENV=".env"
+if
+	[ -e "${TMP_BASE_FILE_DOTENV}" ]
+then
+	export $(
+		grep -v '^#' "${TMP_BASE_FILE_DOTENV}" | xargs
+	) >/dev/null 2>&1
+fi
+
+ALL_ARGS=("$@")
+while [[ "$#" -gt 0 ]]; do
+	case $1 in
+	*) ;;
+	esac
+	shift
+done
+set -- "${ALL_ARGS[@]}"
@@ -0,0 +1,10 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/base/lib/--index-api.sh
+
+# No required environment variables for skill-manager base
@@ -0,0 +1,12 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/base/lib/-ensure-environment-variable.sh
+
+. ./.scripts/base/lib/-environment-show.sh
+
+. ./.scripts/base/lib/-mask.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+. ./.scripts/loggers/lib/--index.sh
+#
+#       --> passed parameters are read & exported environment variables
+#
+. ./.scripts/base/lib/--env-vars-reader.sh
+#
+#       --> required environment variables are validated for existence
+#
+. ./.scripts/base/lib/--env-vars-validator.sh
+#
+#       --> available functions are imported/exported
+#
+. ./.scripts/base/lib/--index-api.sh
+# -------------------------------------------------------------------------------------
@@ -0,0 +1,18 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/--index-api.sh
+
+_base_ensureEnvironmentVariable() {
+  local FUNCTION_NAME="_base_ensureEnvironmentVariable"
+  local ENV_VAR_NAME="$1"
+  _loggers_info "${FUNCTION_NAME}" "ENV_VAR_NAME: ${ENV_VAR_NAME}"
+  if [ -z "${!ENV_VAR_NAME}" ]; then
+    _loggers_error "${FUNCTION_NAME}" "Missing required environment variable: ${ENV_VAR_NAME}. Check .env or .env-* files!"
+    exit 1
+  fi
+}
@@ -0,0 +1,16 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/--index-api.sh
+
+_base_environment_show() {
+	local FUNCTION_NAME="_base_environment_show"
+
+	_loggers_info "${FUNCTION_NAME}" "LOCAL_HOME_DIR: ${LOCAL_HOME_DIR}"
+	_loggers_info "${FUNCTION_NAME}" "LOCAL_HOME_DIR_NAME: ${LOCAL_HOME_DIR_NAME}"
+
+}
@@ -0,0 +1,19 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_base_mask() {
+	local original_value="$1"
+	local RET_VAL
+	if
+		[[ -n "$original_value" && ${#original_value} -gt 2 ]]
+	then
+		RET_VAL="${original_value:0:1}$(printf '%*s' $((${#original_value} - 2)) '' | tr ' ' '*')${original_value: -1}"
+	else
+		RET_VAL="$(printf '%*s' ${#original_value} '' | tr ' ' '*')"
+	fi
+	echo "${RET_VAL}"
+}
@@ -0,0 +1,32 @@
+# https://taskfile.dev
+
+version: "3"
+
+tasks:
+  build:
+    desc: Compile TypeScript source to dist/
+    cmds:
+      - |
+        ./.scripts/cli/api/build.sh {{ .CLI_ARGS }}
+    silent: true
+
+  run:
+    desc: |
+      Run any drawio-tools action against a .drawio file.
+      Usage: task cli:run -- --file="/path/to/diagram.drawio" --action=<action> [--page <index>]
+      Actions: summary, page-summary, page-hierarchy, page-connectors-summary, page-connectors-validation,
+      page-labels-validation, page-shape-bbox-validation, page-orphans, page-recommendations,
+      page-hierarchy-full, page-negative-space-summary, validate
+    cmds:
+      - |
+        ./.scripts/cli/api/run.sh {{ .CLI_ARGS }}
+    silent: true
+
+  validate:
+    desc: |
+      Validate a .drawio file (XML well-formedness + required structure).
+      Usage: task cli:validate -- --file="/path/to/diagram.drawio"
+    cmds:
+      - |
+        ./.scripts/cli/api/validate.sh {{ .CLI_ARGS }}
+    silent: true
@@ -0,0 +1,11 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+set -e
+
+. ./.scripts/cli/lib/--index.sh
+
+_cli__build "$@"
@@ -0,0 +1,11 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+set -e
+
+. ./.scripts/cli/lib/--index.sh
+
+_cli__run "$@"
@@ -0,0 +1,11 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+set -e
+
+. ./.scripts/cli/lib/--index.sh
+
+_cli__validate "$@"
@@ -0,0 +1,15 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+ALL_ARGS=("$@")
+while [[ "$#" -gt 0 ]]; do
+	case $1 in
+	*) ;;
+	esac
+	shift
+done
+set -- "${ALL_ARGS[@]}"
@@ -0,0 +1,10 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/cli/lib/--index-api.sh
+
+# No required environment variables for cli module
@@ -0,0 +1,12 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/cli/lib/-build.sh
+
+. ./.scripts/cli/lib/-run.sh
+
+. ./.scripts/cli/lib/-validate.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+. ./.scripts/loggers/lib/--index.sh
+. ./.scripts/base/lib/--index.sh
+#
+#       --> passed parameters are read & exported environment variables
+#
+. ./.scripts/cli/lib/--env-vars-reader.sh
+#
+#       --> required environment variables are validated for existence
+#
+. ./.scripts/cli/lib/--env-vars-validator.sh
+#
+#       --> available functions are imported/exported
+#
+. ./.scripts/cli/lib/--index-api.sh
+# -------------------------------------------------------------------------------------
@@ -0,0 +1,12 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_cli__build() {
+  local FUNCTION_NAME="_cli__build"
+  _loggers_info "${FUNCTION_NAME}" "Compiling TypeScript source to dist/"
+  pnpm run build
+}
@@ -0,0 +1,12 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_cli__run() {
+  local FUNCTION_NAME="_cli__run"
+  _loggers_info "${FUNCTION_NAME}" "Running drawio-tools CLI"
+  node dist/cli/commands.js "$@"
+}
@@ -0,0 +1,12 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_cli__validate() {
+  local FUNCTION_NAME="_cli__validate"
+  _loggers_info "${FUNCTION_NAME}" "Validating .drawio file via drawio-tools CLI"
+  node dist/cli/commands.js --action validate "$@"
+}
@@ -0,0 +1,18 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+export LOGGER_TRAILING_NEW_LINE_ENABLED="TRUE"
+
+export LOGGER_IS_ENABLED_ERROR=true
+export LOGGER_IS_ENABLED_INFO=true
+export LOGGER_IS_ENABLED_WARN=true
+export LOGGER_IS_ENABLED_DEBUG=true
+export LOGGER_IS_ENABLED_TRACE=false
+
+export LOCAL_STRING_005_SPACES="          "
+export LOCAL_STRING_010_SPACES="${LOCAL_STRING_005_SPACES}${LOCAL_STRING_005_SPACES}"
+export LOCAL_STRING_050_SPACES="${LOCAL_STRING_010_SPACES}${LOCAL_STRING_010_SPACES}${LOCAL_STRING_010_SPACES}${LOCAL_STRING_010_SPACES}${LOCAL_STRING_010_SPACES}"
+export LOCAL_STRING_070_SPACES="${LOCAL_STRING_050_SPACES}${LOCAL_STRING_010_SPACES}${LOCAL_STRING_010_SPACES}"
@@ -0,0 +1,9 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/--env-vars-reader.sh
+. ./.scripts/loggers/lib/--index.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+. ./.scripts/loggers/lib/-info.sh
+. ./.scripts/loggers/lib/-trace.sh
+. ./.scripts/loggers/lib/-debug.sh
+. ./.scripts/loggers/lib/-error.sh
+. ./.scripts/loggers/lib/-warn.sh
+
+. ./.scripts/loggers/lib/-printf--debug.sh
+. ./.scripts/loggers/lib/-printf--info.sh
+. ./.scripts/loggers/lib/-printf--trace.sh
+. ./.scripts/loggers/lib/-printf--warn.sh
+
+. ./.scripts/loggers/lib/-empty-line.sh
+. ./.scripts/loggers/lib/-waiting-dot.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+#
+#       --> passed parameters are read & exported environment variables
+#
+. ./.scripts/loggers/lib/--env-vars-reader.sh
+#
+#       --> available functions are imported/exported
+#
+. ./.scripts/loggers/lib/--index-api.sh
+# -------------------------------------------------------------------------------------
@@ -0,0 +1,20 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_debug() {
+  _loggers_enableLoggerTrailingNewLine
+  if
+    [ "${LOGGER_IS_ENABLED_DEBUG}" = true ]
+  then
+    local TMP_1ST_PARAM="${1}${LOCAL_STRING_070_SPACES}"
+    TMP_1ST_PARAM="${TMP_1ST_PARAM:0:70}"
+    local TMP_LINE="# DEBUG # ${TMP_1ST_PARAM} #     ${2}"
+    echo -e "\033[1;36m${TMP_LINE}\033[0m" >&2
+  fi
+}
@@ -0,0 +1,13 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_emptyLine() {
+  _loggers_enableLoggerTrailingNewLine
+  echo -e "" >&2
+}
@@ -0,0 +1,15 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+_loggers_enableLoggerTrailingNewLine() {
+  if
+    [ -z "$LOGGER_TRAILING_NEW_LINE_DISABLED" ]
+  then
+    echo "" >&2
+    export LOGGER_TRAILING_NEW_LINE_DISABLED="TRUE"
+  fi
+}
@@ -0,0 +1,21 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_error() {
+  _loggers_enableLoggerTrailingNewLine
+  if
+    [ "${LOGGER_IS_ENABLED_ERROR}" = true ]
+  then
+    local TMP_1ST_PARAM="${1}${LOCAL_STRING_070_SPACES}"
+    TMP_1ST_PARAM="${TMP_1ST_PARAM:0:70}"
+    local TMP_LINE="# ERROR # ${TMP_1ST_PARAM} #     $2"
+    echo -e "\033[1;31m${TMP_LINE}\033[0m" >&2
+  fi
+
+}
@@ -0,0 +1,20 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_info() {
+  _loggers_enableLoggerTrailingNewLine
+  if
+    [ "${LOGGER_IS_ENABLED_INFO}" = true ]
+  then
+    local TMP_1ST_PARAM="${1}${LOCAL_STRING_070_SPACES}"
+    TMP_1ST_PARAM="${TMP_1ST_PARAM:0:70}"
+    local TMP_LINE="# INFO  # ${TMP_1ST_PARAM} #     ${2}"
+    echo -e "${TMP_LINE}" >&2
+  fi
+}
@@ -0,0 +1,14 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_loggers_printf__debug() {
+	if
+		[ "${LOGGER_IS_ENABLED_DEBUG}" = true ]
+	then
+		printf '\033[1;36m%s\033[0m\n' "$*" >&2
+	fi
+}
@@ -0,0 +1,14 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_loggers_printf__info() {
+	if
+		[ "${LOGGER_IS_ENABLED_INFO}" = true ]
+	then
+		printf '\033[1;32m%s\033[0m\n' "$*" >&2
+	fi
+}
@@ -0,0 +1,14 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_loggers_printf__trace() {
+	if
+		[ "${LOGGER_IS_ENABLED_TRACE}" = true ]
+	then
+		printf '\033[0;90m%s\033[0m\n' "$*" >&2
+	fi
+}
@@ -0,0 +1,14 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#
+#
+# -------------------------------------------------------------------------------------
+
+_loggers_printf__warn() {
+	if
+		[ "${LOGGER_IS_ENABLED_WARN}" = true ]
+	then
+		printf '\033[1;33m%s\033[0m\n' "$*" >&2
+	fi
+}
@@ -0,0 +1,21 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_trace() {
+  _loggers_enableLoggerTrailingNewLine
+  if
+    [ "${LOGGER_IS_ENABLED_TRACE}" = true ]
+  then
+    local TMP_1ST_PARAM="${1}${LOCAL_STRING_070_SPACES}"
+    TMP_1ST_PARAM="${TMP_1ST_PARAM:0:70}"
+    local TMP_LINE="# TRACE # ${TMP_1ST_PARAM} #     $2"
+    echo -e "\033[0;94m${TMP_LINE}\033[0m" >&2
+  fi
+
+}
@@ -0,0 +1,13 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_waitingDot() {
+  echo -n "." >&2
+  export LOGGER_TRAILING_NEW_LINE_DISABLED=""
+}
@@ -0,0 +1,20 @@
+#!/bin/bash
+# -------------------------------------------------------------------------------------
+#
+#     TOBE ADDED - Licence & Copyright Disclaimer
+#
+# -------------------------------------------------------------------------------------
+
+. ./.scripts/loggers/lib/-enable-trailing-new-line.sh
+
+_loggers_warn() {
+  _loggers_enableLoggerTrailingNewLine
+  if
+    [ "${LOGGER_IS_ENABLED_WARN}" = true ]
+  then
+    local TMP_1ST_PARAM="${1}${LOCAL_STRING_070_SPACES}"
+    TMP_1ST_PARAM="${TMP_1ST_PARAM:0:70}"
+    local TMP_LINE="# WARN  # ${TMP_1ST_PARAM} #     $2"
+    echo -e "\033[1;33m${TMP_LINE}\033[0m" >&2
+  fi
+}