@uxf/scripts 11.122.3 → 11.122.4

package/README.md

@@ -1,35 +1,73 @@
 # @uxf/scripts
 
-# @uxf/scripts
 [![npm](https://img.shields.io/npm/v/@uxf/scripts)](https://www.npmjs.com/package/@uxf/scripts)
 [![size](https://img.shields.io/bundlephobia/min/@uxf/scripts)](https://www.npmjs.com/package/@uxf/scripts)
 [![quality](https://img.shields.io/npms-io/quality-score/@uxf/scripts)](https://www.npmjs.com/package/@uxf/scripts)
 [![license](https://img.shields.io/npm/l/@uxf/scripts)](https://www.npmjs.com/package/@uxf/scripts)
-## uxf-release
+
+Collection of UXF command-line tools for CI pipelines and local project maintenance (releases, dependency checks, sitemap crawling, i18n namespace generation, dead-code detection, and more).
+
+## When to use
+
+Reach for a specific binary from this package when you need one of the CI/maintenance tasks listed below. It is a **CLI-only** package — there is no importable API (`main` points to a non-existent `index.js`); consume it through its `bin` commands, not `import`/`require`.
+
+Most binaries are already available in the UXF Docker images, so CI jobs can call them directly. Locally, run them with `npx <command>`.
+
+## Installation
+
+```
+yarn add -D @uxf/scripts
+```
+
+Requires **Node.js >= 24** (`engines.node`). No peer dependencies. Runtime dependencies (`axios`, `cheerio`, `dayjs`, `fast-glob`, `got`, `madge`, `robots-txt-parser`, `semver`, `yaml`, `yargs`) are bundled.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `uxf-release` | Generate release notes from Git commits, create a GitLab release, notify Slack / Google Chat. |
+| `uxf-push-notifier` | Notify Google Chat when a merge request is merged into (or code is pushed to) the default branch. |
+| `uxf-dependencies-check` | Detect version conflicts and missing/mismatched peer deps across `@uxf/*` packages. |
+| `uxf-audit` | Print a JSON report of Node / Yarn / Next / React and installed `@uxf/*` versions. |
+| `uxf-claude-sync` | Download global guidelines from a URL into a `CLAUDE.md` file. |
+| `uxf-i18n-namespaces-gen` | Generate an `i18n-pages.json` mapping routes to the translation namespaces they use. |
+| `uxf-unused` | Find (and optionally delete) unused files in a Next.js project. |
+| `uxf-sitemap-check` | Crawl a sitemap and check all URLs for HTTP errors, duplicates, and missing pages. |
+| `uxf-sitemap-meta-export` | Crawl a sitemap and export page meta tags (title, description, OG) to `export.csv`. |
+| `uxf-lunch` | Post today's lunch menu to a Slack channel. |
+
+Every command accepts `-h` / `--help`.
+
+### uxf-release
+
+Reads commits on `master` since the last Git tag, generates release notes (grouped by conventional-commit type, linking YouTrack issues), creates a GitLab release, and posts a summary to Slack and/or Google Chat. Warns when the range contains DB migration files.
+
 ```
-UXF release helper
 Usage:
   uxf-release [options]
 
 Environment variables:
-  GITLAB_TOKEN      - required
-  CI_SERVER_URL     - required - setting by GitLab CI
-  CI_PROJECT_ID     - required - setting by GitLab CI
-  SLACK_WEBHOOK_URL - optional
-
-Options
-  -p, --project-id  GitLab project id (or use environment variable
-                    CI_PROJECT_ID)                                      [number]
-  -d, --dry-run     Skip publishing and sending slack notification     [boolean]
-  -h, --help        Show help                                          [boolean]
+  GITLAB_TOKEN       - required
+  CI_SERVER_URL      - required - set by GitLab CI
+  CI_PROJECT_ID      - required - set by GitLab CI
+  SLACK_TOKEN        - optional
+  GOOGLE_WEBHOOK_URL - optional
 
 Options:
-      --version  Show version number                                   [boolean]
+  -t, --tag-prefix           Git tag prefix                             [string]
+  -g, --google-chat-webhook  Google Chat webhook URL                    [string]
+  -m, --message              Message title                              [string]
+  -p, --project-id           GitLab project id (or use CI_PROJECT_ID)   [number]
+  -s, --slack-channel        Slack channel for notification             [string]
+  -d, --dry-run              Skip publishing and notifications         [boolean]
+  -h, --help                 Show help                                 [boolean]
 ```
 
-### How to use in gitlab pipeline `.gitlab-ci.yml`
+`--project-id` overrides `CI_PROJECT_ID`; `--google-chat-webhook` falls back to `GOOGLE_WEBHOOK_URL`.
 
-set environment variable `GITLAB_TOKEN` in GitLab CI configuration and create `.gitlab-ci.yml`
+#### Use in a GitLab pipeline (`.gitlab-ci.yml`)
+
+Set `GITLAB_TOKEN` in the GitLab CI/CD variables, then:
 
 ```yaml
 # .gitlab-ci.yml
@@ -37,55 +75,69 @@ stages:
   - release
 
 release:
-  image: node:12-buster-slim
+  image: node:24
   stage: release
   before_script:
-    - yarn global add @uxf/release
+    - yarn global add @uxf/scripts
   script:
     # ... deploy project ...
     - uxf-release
 ```
 
-## uxf-push-notifier
+### uxf-push-notifier
+
+Runs in GitLab CI. If the current commit is the merge commit of a merged MR, it posts a Google Chat message with the MR title, author, approver, and who merged it; otherwise it posts the list of pushed commits. Requires `GITLAB_TOKEN` plus the standard GitLab CI variables (`CI_SERVER_URL`, `CI_PROJECT_ID`, `CI_COMMIT_SHA`, `CI_COMMIT_BEFORE_SHA`, `CI_COMMIT_REF_NAME`).
+
+```
+Usage:
+  uxf-push-notifier [options]
+
+Environment variables:
+  GITLAB_TOKEN - required
+
+Options:
+  -g, --google-chat-webhook-url  Target Google Chat webhook URL         [string]
+  -h, --help                     Show help                             [boolean]
+```
 
 ```yaml
 stages:
   - notify
 
 notify-push:
-    image: node:20
-    stage: notify
-    except: [schedules]
-    only:
-        - develop # default branch
-    script:
-        - yarn global add @uxf/scripts # uxf scripts are installed in uxf docker images by default
-        - uxf-push-notifier --google-chat-webhook-url=$GOOGLE_CHAT_WEBHOOK
+  image: node:24
+  stage: notify
+  except: [schedules]
+  only:
+    - develop # default branch
+  script:
+    - yarn global add @uxf/scripts # already present in UXF Docker images
+    - uxf-push-notifier --google-chat-webhook-url=$GOOGLE_CHAT_WEBHOOK
 ```
 
-## uxf-dependencies-check
+### uxf-dependencies-check
 
 All-in-one dependency health check for projects using `@uxf/*` packages. Runs two checks:
 
 1. **Version conflict detection** — reports dependencies where the project and/or `@uxf/*` packages themselves resolve to different versions. Transitive-only duplicates (a dep pulled in by unrelated third-party packages at a different version) are ignored, since they don't affect `@uxf/*` compatibility.
-2. **Peer dependency check** — verifies that all `peerDependencies` of installed `@uxf/*` packages are present and version-matched
+2. **Peer dependency check** — verifies that all `peerDependencies` of installed `@uxf/*` packages are present and version-matched.
 
 Supports **yarn**, **npm**, **pnpm**, and **bun**. The package manager is auto-detected from the lock file.
 
-```bash
+```
 Usage:
   uxf-dependencies-check [options]
 
 Options:
-  --fix           Auto-install missing/mismatched peer dependencies
-  --dry-run       Show what would be installed without changes
-  -e, --exclude   Packages to ignore in conflict check              [array]
-  -h, --help      Show help                                        [boolean]
+  --fix           Auto-install missing/mismatched peer dependencies    [boolean]
+  --dry-run       Show what would be installed without changes         [boolean]
+  -e, --exclude   Packages to ignore in conflict check                   [array]
+  -h, --help      Show help                                            [boolean]
 ```
 
 Build-time dependencies (`yargs`, `fast-glob`) are automatically ignored in the conflict check.
 
-### Examples
+#### Examples
 
 ```bash
 # Run both checks (exits with code 1 if issues found)
@@ -101,7 +153,7 @@ npx uxf-dependencies-check --dry-run
 npx uxf-dependencies-check --exclude lodash dayjs
 ```
 
-### Ignoring known conflicts
+#### Ignoring known conflicts
 
 Transitive-only duplicates (caused by unrelated third-party packages, e.g. `@udecode/plate-floating` pulling an old `@floating-ui/react` alongside a newer one declared by an `@uxf/*` package) are filtered out automatically and do not need to be ignored.
 
@@ -118,31 +170,146 @@ For genuine declarer conflicts that you've consciously accepted — e.g. two `@u
 
 Ignored conflicts are still printed as informational output but do **not** cause a non-zero exit code. The `--exclude` CLI flag hides packages completely (not printed at all).
 
-### What it checks
+#### What it checks
+
+- Parses the lock file (`yarn.lock` / `package-lock.json` / `pnpm-lock.yaml` / `bun.lock`) to find dependencies with multiple installed versions.
+- For each candidate, resolves the version actually seen by each *declarer* (the project itself and any `@uxf/*` package that directly declares the dep). A conflict is reported only when these declarers land on different versions — transitive-only duplicates from unrelated third-party packages are filtered out.
+- Scans all `@uxf/*` packages in your `dependencies` / `devDependencies`.
+- Reads each package's `peerDependencies` from `node_modules`.
+- Skips `@uxf/*`, `react`, `react-dom`, and `next` (you manage these yourself).
+- Reports missing dependencies and version mismatches.
+- Distinguishes between prod and dev dependencies — peer deps required only by `devDependencies` are installed with `-D`.
+- With `--fix`, auto-installs missing peer deps using the detected package manager.
 
-- Parses the lock file (yarn.lock / package-lock.json / pnpm-lock.yaml / bun.lock) to find dependencies with multiple installed versions
-- For each candidate, resolves the version actually seen by each *declarer* (the project itself and any `@uxf/*` package that directly declares the dep). A conflict is reported only when these declarers land on different versions — transitive-only duplicates from unrelated third-party packages are filtered out
-- Scans all `@uxf/*` packages in your `dependencies` / `devDependencies`
-- Reads each package's `peerDependencies` from `node_modules`
-- Skips `@uxf/*`, `react`, `react-dom`, and `next` (you manage these yourself)
-- Reports missing dependencies and version mismatches
-- Distinguishes between prod and dev dependencies — peer deps required only by `devDependencies` are installed with `-D`
-- With `--fix`, auto-installs missing peer deps using the detected package manager
+### uxf-audit
 
-## uxf-lunch
+Prints a JSON report of the current environment to stdout: Node, Yarn, Next, React, and react-dom versions plus the resolved version of every installed `@uxf/*` package (duplicates are flagged with `isError: true`). Supports Yarn 1 and Yarn 4, auto-detected from `yarn -v`. Run it inside the target project. No options.
 
 ```bash
-UXF lunch
+npx uxf-audit
+```
+
+### uxf-claude-sync
+
+Downloads content from a URL and writes it under a `# Global guidelines` heading in the target file (default `CLAUDE.md`). If the heading exists, the content below it is replaced; otherwise the section is appended (or a new file is created).
+
+```
 Usage:
-  uxf-lunch [options]
+  uxf-claude-sync [options]
+
+Options:
+  --url       Global guidelines URL                                     [string]
+  --fileName  Target file name (default: CLAUDE.md)                     [string]
+  -h, --help  Show help
+```
+
+### uxf-i18n-namespaces-gen
+
+Walks a Next.js pages directory, follows each page's import graph (including `@uxf/*` packages and `tsconfig` path aliases), collects the translation namespaces referenced by `t(...)` calls and `<Trans>` components, and writes a route → namespaces map to a JSON file.
+
+```
+Usage:
+  uxf-i18n-namespaces-gen [options]
+
+Options:
+  -i, --include           Path prefixes to limit traversal to      [array] [default: []]
+  -o, --output            Output file            [default: "i18n-pages.json"]
+  -n, --defaultNamespace  Namespaces applied to every page  [array] [default: ["common"]]
+  -p, --pagesDirectory    Pages directory                 [default: "src/pages"]
+  -h, --help              Show help
+```
+
+Namespaces found on `/_app` are merged into the global `*` entry.
+
+### uxf-unused
+
+Finds files in a Next.js project that are not reachable from the pages import graph, prints them, and (with `--removeFiles`) deletes them. Use `--debug` to dump intermediate JSON files (`uxf-unused-*.json`) into the working directory.
+
+```
+Usage:
+  uxf-unused [options]
+
+Options:
+  -p, --pagesDirectory    Glob of page entry points
+                          [default: "src/pages/**/*.(ts|tsx)"]
+  -f, --allFilesDirectory Glob of all candidate files
+                          [default: "src/**/*.(ts|tsx)"]
+  -r, --removeFiles       Delete the unused files          [boolean] [default: false]
+  -d, --debug             Write intermediate JSON files    [boolean] [default: false]
+  -h, --help              Show help
+```
+
+### uxf-sitemap-check
+
+Crawls a sitemap and requests every URL, reporting HTTP errors, duplicate sitemap entries, and (optionally) indexable pages missing from the sitemap. Can also follow nested page links and images. Sends a summary to Google Chat when errors are found and exits with code 1.
+
+```
+Usage:
+  uxf-sitemap-check [options]
 
 Environment variables:
-  SLACK_TOKEN - required
+  HTTP_USERNAME - optional
+  HTTP_PASSWORD - optional
+
+Options:
+  --url                      Sitemap URL (required)                     [string]
+  -u, --http-username        Basic-auth username (or HTTP_USERNAME)     [string]
+  -p, --http-password        Basic-auth password (or HTTP_PASSWORD)     [string]
+  --skip                     Number of leading URLs to skip             [number]
+  --with-nested              Also test links found on each page        [boolean]
+  --with-images              Also test images found on each page       [boolean]
+  --check-missing            Report indexable pages missing from the
+                             sitemap (requires --with-nested)          [boolean]
+  --google-chat-webhook-url  Where to send the results                  [string]
+  -h, --help                 Show help                                 [boolean]
+```
+
+### uxf-sitemap-meta-export
 
-Options
-      --slack-channel  Slack channel                                    [string]
+Crawls a sitemap and writes a semicolon-separated `export.csv` (columns: `url;title;og:title;description;og:description`) into the working directory. The sitemap URL is taken from `--url` or the `SITEMAP_URL` environment variable.
+
+```
+Usage:
+  uxf-sitemap-meta-export [options]
+
+Environment variables:
+  SITEMAP_URL       - required (or use --url)
+  HTTP_USERNAME     - optional
+  HTTP_PASSWORD     - optional
+  SLACK_WEBHOOK_URL - optional
+
+Options:
+  --url                Sitemap URL (or use SITEMAP_URL)                 [string]
+  -u, --http-username  Basic-auth username (or HTTP_USERNAME)           [string]
+  -p, --http-password  Basic-auth password (or HTTP_PASSWORD)           [string]
+  -d, --dry-run        Skip the Slack notification                     [boolean]
   -h, --help           Show help                                       [boolean]
+```
+
+### uxf-lunch
+
+Fetches the daily menu (Hotel Radnice) and posts it as a formatted message to a Slack channel.
+
+```
+Usage:
+  uxf-lunch [options]
+
+Environment variables:
+  SLACK_TOKEN - required
 
 Options:
-      --version  Show version number
+  --slack-channel  Slack channel (required)                            [string]
+  -h, --help       Show help
 ```
+
+## Gotchas
+
+- **CLI-only, no importable API.** `main` references a `index.js` that is not shipped; use the `bin` commands.
+- **CI-oriented defaults.** `uxf-release`, `uxf-push-notifier`, and `uxf-sitemap-meta-export` expect GitLab CI / environment variables and mostly make sense inside a pipeline.
+- **`uxf-sitemap-check --check-missing`** only works together with `--with-nested`; used alone it exits with code 1.
+- **`uxf-unused --removeFiles` deletes files** on disk — run without it (or with `--debug`) first to review the list.
+- **`uxf-merge-requests-notifier`** exists in the source tree but is **not** exposed as a `bin` command; it is run internally via the package's `run:mr-notifier` npm script and is not installed for consumers.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/@uxf/scripts)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/scripts",
-    "version": "11.122.3",
+    "version": "11.122.4",
     "description": "",
     "main": "index.js",
     "bin": {
@@ -50,6 +50,6 @@
         "@types/react-dom": "18.3.7",
         "@types/semver": "^7.7.1",
         "@uxf/core": "11.114.0",
-        "@uxf/ui": "11.122.3"
+        "@uxf/ui": "11.122.4"
     }
 }