Swith to v0.20.3

.env.example

@@ -5,5 +5,5 @@ TRAEFIK_NETWORK=internal
 TRAEFIK_CERT_RESOLVER=netcup
 
 # Keep these two values paired when deploying a newer published toolbox release.
-TOOLBOX_RELEASE_VERSION=0.20.0
-TOOLBOX_RELEASE_SHA256=450618902a1ee87405da463881e6f51f685691c2081259aff9c25a4aa6fe22ed
+TOOLBOX_RELEASE_VERSION=0.20.3
+TOOLBOX_RELEASE_SHA256=1e743fda8f6d1ca5c77798029351585bf6673a3410892d27e5ad17c9f6bcf0bf

Containerfile.release

@@ -2,8 +2,8 @@ ARG NGINX_IMAGE=nginxinc/nginx-unprivileged:1.31.3-alpine@sha256:18d67281256ded3
 
 FROM ${NGINX_IMAGE} AS release
 
-ARG TOOLBOX_RELEASE_VERSION=0.20.0
-ARG TOOLBOX_RELEASE_SHA256=450618902a1ee87405da463881e6f51f685691c2081259aff9c25a4aa6fe22ed
+ARG TOOLBOX_RELEASE_VERSION=0.20.3
+ARG TOOLBOX_RELEASE_SHA256=1e743fda8f6d1ca5c77798029351585bf6673a3410892d27e5ad17c9f6bcf0bf
 ARG TOOLBOX_RELEASE_BASE_URL=https://git.add-ideas.de/lotobo/toolbox-portal/releases/download
 
 RUN set -eu; \
@@ -43,6 +43,7 @@ RUN set -eu; \
     test -f /tmp/toolbox/apps/diff/toolbox-app.json; \
     test -f /tmp/toolbox/apps/time/toolbox-app.json; \
     test -f /tmp/toolbox/apps/text/toolbox-app.json; \
+    test -f /tmp/toolbox/apps/translator/toolbox-app.json; \
     test -f /tmp/toolbox/apps/unicode/toolbox-app.json; \
     test -f /tmp/toolbox/apps/flow/toolbox-app.json; \
     test -f /tmp/toolbox/apps/subtitle/toolbox-app.json; \

README.md

@@ -99,7 +99,17 @@ Deploy a fresh clone with:
 ```sh
 git clone https://git.add-ideas.de/lotobo/toolbox-portal.git
 cd toolbox-portal
-docker compose up -d --build
+./scripts/deploy-update.sh
+```
+
+If you prefer the inline command:
+
+```sh
+git fetch origin --tags && \
+git pull --ff-only origin main && \
+{ TAG="$(git describe --tags --exact-match 2>/dev/null || git describe --tags --abbrev=0 2>/dev/null || true)"; \
+  if [ -n "$TAG" ]; then echo "$TAG"; else echo "warning: no matching tags found"; fi; } && \
+docker compose up -d --build && \
 docker compose ps
 ```
 
@@ -111,6 +121,26 @@ release version, and matching checksum can be overridden through environment
 variables; copy `.env.example` to `.env` only when an override is needed. For
 example, set `TOOLBOX_HOST=staging.toolbox.add-ideas.de` for a staging host.
 
+## One-shot release wrapper
+
+For release assembly and publishing, use the repository-local wrapper:
+
+```sh
+./scripts/release.sh
+```
+
+That script performs (in order):
+
+- optional `npm test`
+- `npm run build`
+- `npm run assemble` (using the lockfile’s `releaseVersion`)
+- tag and push (`v<releaseVersion>`)
+- publish/update a Gitea release and upload
+  `add-ideas-toolbox-<version>.zip` and `.sha256`
+
+Useful flags include `--skip-tests`, `--skip-git-push`, `--skip-publish`,
+`--tag`, `--owner`, `--repo`, and `--dry-run`.
+
 The same container also exposes only the packaged authentication app at
 `https://auth.toolbox.add-ideas.de/`. Traefik adds the internal `/apps/auth`
 prefix while the public URL remains `/`, so assets remain relative and the browser

compose.example.yaml

@@ -3,7 +3,7 @@ services:
     build:
       context: .
       dockerfile: Containerfile
-    image: git.add-ideas.de/lotobo/toolbox:0.20.0
+    image: git.add-ideas.de/lotobo/toolbox:0.20.3
     restart: unless-stopped
     read_only: true
     ports:

compose.yaml

@@ -6,9 +6,9 @@ services:
       context: .
       dockerfile: Containerfile.release
       args:
-        TOOLBOX_RELEASE_VERSION: "${TOOLBOX_RELEASE_VERSION:-0.20.0}"
-        TOOLBOX_RELEASE_SHA256: "${TOOLBOX_RELEASE_SHA256:-450618902a1ee87405da463881e6f51f685691c2081259aff9c25a4aa6fe22ed}"
-    image: "git.add-ideas.de/lotobo/toolbox:${TOOLBOX_RELEASE_VERSION:-0.20.0}"
+        TOOLBOX_RELEASE_VERSION: "${TOOLBOX_RELEASE_VERSION:-0.20.3}"
+        TOOLBOX_RELEASE_SHA256: "${TOOLBOX_RELEASE_SHA256:-66f02f95092ef80b9e49cda91c8401400e2ee1d2c640ab20a3a7810bf265c2c7}"
+    image: "git.add-ideas.de/lotobo/toolbox:${TOOLBOX_RELEASE_VERSION:-0.20.3}"
     restart: unless-stopped
     read_only: true
     tmpfs:

package.json

@@ -18,7 +18,9 @@
     "check": "npm run format:check && npm run lint && npm run test && npm run build",
     "licenses:generate": "node scripts/licenses.mjs",
     "assemble": "node scripts/assemble.mjs",
-    "package:static": "node scripts/package-static.mjs"
+    "package:static": "node scripts/package-static.mjs",
+    "release:update": "node scripts/update-release-lock.mjs",
+    "release": "scripts/release.sh"
   },
   "dependencies": {
     "@add-ideas/toolbox-contract": "^0.3.0",

public/toolbox.catalog.json

@@ -109,6 +109,10 @@
       "manifest": "./apps/text/toolbox-app.json",
       "enabled": true
     },
+    {
+      "manifest": "./apps/translator/toolbox-app.json",
+      "enabled": true
+    },
     {
       "manifest": "./apps/unicode/toolbox-app.json",
       "enabled": true

release/toolbox.lock.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./toolbox-release-lock.schema.json",
   "schemaVersion": 1,
-  "releaseVersion": "0.20.0",
+  "releaseVersion": "0.20.3",
   "portalVersion": "0.2.23",
   "catalogue": {
     "id": "de.add-ideas.toolbox",
@@ -188,6 +188,13 @@
       "sha256": "a1b635278da1baf844051fb0bbfc94022596bb674091c4c39ec164cf34bd5f62",
       "target": "text"
     },
+    {
+      "id": "de.add-ideas.translator-tools",
+      "version": "0.1.2",
+      "artifact": "https://git.add-ideas.de/lotobo/translator-tools/releases/download/v0.1.2/translator-tools-0.1.2.zip",
+      "sha256": "2ff24f97e0c3893c4d31dc347bd760d91a0d4a565fb392ec1a1b22ba9835c34f",
+      "target": "translator"
+    },
     {
       "id": "de.add-ideas.unicode-tools",
       "version": "0.2.0",

scripts/deploy-update.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${PROJECT_DIR}"
+
+git fetch origin --tags
+git pull --ff-only origin main
+
+if ! TAG="$(git describe --tags --exact-match 2>/dev/null)"; then
+  TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+  if [ -z "${TAG}" ]; then
+    echo "warning: current commit is untagged and no tagged ancestor was found"
+  else
+    echo "warning: current commit is untagged; nearest tag is ${TAG}"
+  fi
+else
+  echo "tagged: ${TAG}"
+fi
+
+docker compose up -d --build
+docker compose ps

scripts/deployment.test.ts

@@ -53,6 +53,7 @@ const expectedAppTargets = [
   'diff',
   'time',
   'text',
+  'translator',
   'unicode',
   'flow',
   'subtitle',

scripts/publish-release.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { readFile, access } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function usage() {
+  return `Usage: node scripts/publish-release.mjs [options]
+
+Uploads prepared release artifacts to a Gitea release.
+
+Options:
+  --api-base URL          Gitea API base (default: https://git.add-ideas.de/api/v1)
+  --owner OWNER           Gitea repository owner (default: lotobo)
+  --repo REPO             Gitea repository (default: toolbox-portal)
+  --tag TAG               Release tag, e.g. v0.20.3 (default: from --lock-file)
+  --target HASH           Target commit SHA for release creation
+  --name NAME             Release name
+  --body BODY             Optional release body
+  --archive PATH          Release ZIP path
+  --checksum PATH         SHA256 file path
+  --lock-file PATH        Release lock file (default: release/toolbox.lock.json)
+  --token TOKEN           Gitea API token; defaults to GITEA_TOKEN env
+  --dry-run               Print actions without contacting Gitea
+  --help                  Show this help
+`;
+}
+
+function parseArguments(argv) {
+  if (argv.includes('--help')) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  const args = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) throw new Error(`Unknown argument ${arg}`);
+
+    if (arg === '--dry-run') {
+      args.set(arg, true);
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) throw new Error(`Missing value for ${arg}`);
+    args.set(arg, value);
+    index += 1;
+  }
+
+  return {
+    apiBase: args.get('--api-base') ?? 'https://git.add-ideas.de/api/v1',
+    owner: args.get('--owner') ?? 'lotobo',
+    repo: args.get('--repo') ?? 'toolbox-portal',
+    tag: args.get('--tag'),
+    target: args.get('--target'),
+    name: args.get('--name') ?? 'add-ideas Toolbox release',
+    body: args.get('--body'),
+    archive: args.get('--archive'),
+    checksum: args.get('--checksum'),
+    lockFile: args.get('--lock-file') ?? 'release/toolbox.lock.json',
+    token: args.get('--token') ?? process.env.GITEA_TOKEN,
+    dryRun: args.get('--dry-run') === true,
+  };
+}
+
+async function readTokenFromEnvFile() {
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  const homeConfig = process.env.HOME
+    ? `${process.env.HOME}/.config/gitea/gitea.env`
+    : null;
+
+  const candidates = [];
+  if (xdgConfig) candidates.push(`${xdgConfig}/gitea/gitea.env`);
+  if (homeConfig) candidates.push(homeConfig);
+
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+    } catch {
+      continue;
+    }
+
+    const fileContent = await readFile(candidate, 'utf8');
+    const tokenLine = fileContent
+      .split('\n')
+      .map((line) => line.trim())
+      .find((line) => line.startsWith('GITEA_TOKEN='));
+
+    if (!tokenLine) continue;
+
+    const token = tokenLine.split('=', 2)[1]?.trim();
+    if (token) return token;
+  }
+
+  return null;
+}
+
+async function giteaRequest(url, options, { allowNotFound = false } = {}) {
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      Accept: 'application/json',
+      ...(options.headers ?? {}),
+    },
+  });
+
+  if (allowNotFound && response.status === 404) {
+    return { notFound: true, status: 404 };
+  }
+
+  const text = await response.text();
+  const payload = text ? (() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { raw: text };
+    }
+  })() : null;
+
+  if (!response.ok) {
+    const detail = payload && typeof payload === 'object' && payload.error
+      ? payload.error
+      : payload?.raw ?? text ?? '';
+    throw new Error(`Gitea API request failed (${response.status} ${response.statusText}): ${detail}`);
+  }
+
+  return payload;
+}
+
+function sha256Digest(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function parseChecksumFile(raw) {
+  const [first] = String(raw).trim().split(/\s+/);
+  return first?.toLowerCase() ?? '';
+}
+
+function parseReleaseVersionFromLock(lockJson) {
+  return lockJson.releaseVersion;
+}
+
+async function run() {
+  const options = parseArguments(process.argv.slice(2));
+
+  const lock = await readFile(options.lockFile, 'utf8');
+  const lockJson = JSON.parse(lock);
+  if (!SEMVER.test(lockJson.releaseVersion)) {
+    throw new Error(`Invalid releaseVersion in lock: ${lockJson.releaseVersion}`);
+  }
+
+  const releaseVersion = parseReleaseVersionFromLock(lockJson);
+  const releaseTag = options.tag ?? `v${releaseVersion}`;
+  const dryRun = options.dryRun === true;
+
+  let token = options.token;
+  if (!token && !dryRun) token = await readTokenFromEnvFile();
+  if (!token && !dryRun) {
+    throw new Error('GITEA_TOKEN is required. Set env or provide --token.');
+  }
+  if (!token && dryRun) token = 'dry-run-token';
+
+  if (!options.archive) {
+    throw new Error('Missing --archive');
+  }
+  if (!options.checksum) {
+    throw new Error('Missing --checksum');
+  }
+
+  const archive = path.resolve(options.archive);
+  const checksumFile = path.resolve(options.checksum);
+
+  const [archiveData, checksumRaw] = await Promise.all([
+    readFile(archive),
+    readFile(checksumFile, 'utf8'),
+  ]);
+
+  const expectedChecksum = parseChecksumFile(checksumRaw);
+  const computedChecksum = sha256Digest(archiveData);
+  if (!expectedChecksum) {
+    throw new Error(`Checksum file is empty: ${checksumFile}`);
+  }
+  if (!/^[a-f0-9]{64}$/i.test(expectedChecksum)) {
+    throw new Error(`Invalid checksum format in ${checksumFile}`);
+  }
+  if (expectedChecksum.toLowerCase() !== computedChecksum.toLowerCase()) {
+    throw new Error(
+      `Checksum mismatch for ${options.archive}. computed=${computedChecksum} file=${expectedChecksum}`
+    );
+  }
+
+  if (dryRun) {
+    console.log(`DRY-RUN: would ensure or create release ${releaseTag} on ${options.owner}/${options.repo}.`);
+    console.log(`DRY-RUN: would upload assets ${path.basename(archive)} and ${path.basename(checksumFile)}.`);
+    return;
+  }
+
+  const apiBase = options.apiBase.replace(/\/+$/, '');
+  const releasePrefix = `${apiBase}/repos/${options.owner}/${options.repo}`;
+  const auth = `token ${token}`;
+
+  const headers = { Authorization: auth };
+  const tagUrl = `${releasePrefix}/releases/tags/${encodeURIComponent(releaseTag)}`;
+  const tagLookup = await giteaRequest(
+    tagUrl,
+    { method: 'GET', headers },
+    { allowNotFound: true }
+  );
+
+  let release;
+  if (tagLookup?.notFound) {
+    const body = {
+      tag_name: releaseTag,
+      target_commitish: options.target || 'main',
+      name: options.name,
+      body:
+        options.body
+        || `Automated release of add-ideas toolbox ${releaseTag} from lock release ${releaseVersion}.`,
+      draft: false,
+      prerelease: false,
+    };
+    if (dryRun) {
+      console.log(`DRY-RUN: would create release ${releaseTag} on ${options.owner}/${options.repo}`);
+      release = { id: '<dry-run>', assets: [] };
+    } else {
+      release = await giteaRequest(`${releasePrefix}/releases`, {
+        method: 'POST',
+        headers: {
+          ...headers,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      });
+      console.log(`Created release ${releaseTag} (${release.id})`);
+    }
+  } else {
+    release = tagLookup;
+    if (dryRun) {
+      console.log(`DRY-RUN: would reuse existing release ${releaseTag} (${release?.id ?? 'unknown'})`);
+    } else {
+      console.log(`Using existing release ${releaseTag} (${release.id})`);
+    }
+  }
+
+  if (dryRun) {
+    console.log('DRY-RUN: would upload assets:', options.archive, options.checksum);
+    return;
+  }
+
+  const existingAssets = release.assets ?? [];
+  const candidateAssets = [
+    { path: archive, name: path.basename(archive) },
+    { path: checksumFile, name: path.basename(checksumFile) },
+  ];
+
+  for (const asset of candidateAssets) {
+    const duplicate = existingAssets.find((entry) => entry.name === asset.name);
+    if (duplicate) {
+      console.log(`Deleting existing asset ${asset.name} from release ${releaseTag}`);
+      await giteaRequest(
+        `${releasePrefix}/releases/assets/${duplicate.id}`,
+        { method: 'DELETE', headers },
+        { allowNotFound: true }
+      );
+    }
+
+    const payload = await readFile(asset.path);
+    const form = new FormData();
+    form.set('attachment', new Blob([payload]), asset.name);
+
+    console.log(`Uploading ${asset.name}`);
+    await giteaRequest(
+      `${releasePrefix}/releases/${release.id}/assets?name=${encodeURIComponent(asset.name)}`,
+      {
+        method: 'POST',
+        headers,
+        body: form,
+      }
+    );
+  }
+
+  console.log(`Release ${releaseTag} published on ${options.owner}/${options.repo}`);
+}
+
+run().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

scripts/release.sh

@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${PROJECT_DIR}"
+
+usage() {
+  cat <<'USAGE'
+Usage: scripts/release.sh [options]
+
+Bundles the current lockfile into a portal archive and publishes the release to Gitea.
+
+Options:
+  --lock PATH              Lock file to use (default: release/toolbox.lock.json)
+  --tag TAG                Release tag to create/push (default: v<releaseVersion>)
+  --owner OWNER            Gitea owner/org (default: lotobo)
+  --repo REPO              Gitea repository (default: toolbox-portal)
+  --api-base URL           Gitea API base URL (default: https://git.add-ideas.de/api/v1)
+  --remote REMOTE          Git remote used to push the tag (default: origin)
+  --build-dir DIR          Build directory (default: build)
+  --output-subdir DIR       Assembled output directory under build-dir (default: toolbox)
+  --skip-tests             Skip npm test
+  --skip-assemble          Skip npm run assemble
+  --skip-build             Skip npm run build
+  --skip-tag               Skip tagging/push of the release tag
+  --skip-git-push          Skip pushing git branch and tag
+  --skip-publish           Skip Gitea release publish/upload
+  --force                  Force overwrite of build outputs
+  --dry-run                Print commands without running remote publishing operations
+  --help                   Show this help
+
+Environment:
+  GITEA_TOKEN             Personal token for Gitea API calls
+  GITEA_API_BASE          Optional override for API base URL
+
+Examples:
+  scripts/release.sh
+  scripts/release.sh --tag v0.20.4 --skip-tests
+USAGE
+}
+
+LOCK_FILE="release/toolbox.lock.json"
+OWNER="lotobo"
+REPO="toolbox-portal"
+API_BASE="${GITEA_API_BASE:-https://git.add-ideas.de/api/v1}"
+REMOTE="origin"
+BUILD_DIR="build"
+OUTPUT_SUBDIR="toolbox"
+SKIP_TESTS=0
+SKIP_ASSEMBLE=0
+SKIP_BUILD=0
+SKIP_TAG=0
+SKIP_GIT_PUSH=0
+SKIP_PUBLISH=0
+FORCE=0
+DRY_RUN=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --lock)
+      LOCK_FILE="$2"
+      shift 2
+      ;;
+    --tag)
+      TAG_OVERRIDE="$2"
+      shift 2
+      ;;
+    --owner)
+      OWNER="$2"
+      shift 2
+      ;;
+    --repo)
+      REPO="$2"
+      shift 2
+      ;;
+    --api-base)
+      API_BASE="$2"
+      shift 2
+      ;;
+    --remote)
+      REMOTE="$2"
+      shift 2
+      ;;
+    --build-dir)
+      BUILD_DIR="$2"
+      shift 2
+      ;;
+    --output-subdir)
+      OUTPUT_SUBDIR="$2"
+      shift 2
+      ;;
+    --skip-tests)
+      SKIP_TESTS=1
+      shift
+      ;;
+    --skip-assemble)
+      SKIP_ASSEMBLE=1
+      shift
+      ;;
+    --skip-build)
+      SKIP_BUILD=1
+      shift
+      ;;
+    --skip-tag)
+      SKIP_TAG=1
+      shift
+      ;;
+    --skip-git-push)
+      SKIP_GIT_PUSH=1
+      shift
+      ;;
+    --skip-publish)
+      SKIP_PUBLISH=1
+      shift
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+run() {
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "DRY-RUN: $*"
+    return 0
+  fi
+
+  "$@"
+}
+
+RELEASE_VERSION="$(node -e "const fs=require('fs');const path=process.argv[1];const lock=JSON.parse(fs.readFileSync(path,'utf8'));if(!lock?.releaseVersion){process.exit(1);}console.log(lock.releaseVersion);" "$LOCK_FILE")"
+if [ -z "$RELEASE_VERSION" ]; then
+  echo "releaseVersion could not be read from ${LOCK_FILE}" >&2
+  exit 1
+fi
+
+if [ -n "${TAG_OVERRIDE:-}" ]; then
+  RELEASE_TAG="$TAG_OVERRIDE"
+else
+  RELEASE_TAG="v${RELEASE_VERSION}"
+fi
+
+ZIP_FILE="${BUILD_DIR}/add-ideas-toolbox-${RELEASE_VERSION}.zip"
+CHECKSUM_FILE="${ZIP_FILE}.sha256"
+TARGET_DIR="${BUILD_DIR}/${OUTPUT_SUBDIR}"
+
+if [ "$SKIP_TESTS" -eq 0 ]; then
+  run npm test
+fi
+
+if [ "$SKIP_BUILD" -eq 0 ]; then
+  run npm run build
+fi
+
+if [ "$SKIP_ASSEMBLE" -eq 0 ]; then
+  ASSEMBLE_ARGS=(
+    npm
+    run
+    assemble
+    --
+    --lock
+    "$LOCK_FILE"
+    --portal-dist
+    dist
+    --output
+    "$TARGET_DIR"
+    --archive
+    "$ZIP_FILE"
+  )
+  if [ "$FORCE" -eq 1 ]; then
+    ASSEMBLE_ARGS+=(--force)
+  fi
+  run "${ASSEMBLE_ARGS[@]}"
+fi
+
+if [ ! -s "$ZIP_FILE" ]; then
+  echo "Release archive missing: $ZIP_FILE" >&2
+  exit 1
+fi
+
+if [ ! -s "$CHECKSUM_FILE" ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "DRY-RUN: would create ${CHECKSUM_FILE}"
+  else
+    sha256sum "$ZIP_FILE" > "$CHECKSUM_FILE"
+  fi
+fi
+
+if [ "$SKIP_TAG" -eq 0 ]; then
+  if git rev-parse -q --verify "refs/tags/${RELEASE_TAG}" >/dev/null; then
+    CURRENT_COMMIT="$(git rev-parse "${RELEASE_TAG}^{commit}")"
+    HEAD_COMMIT="$(git rev-parse HEAD)"
+    if [ "$CURRENT_COMMIT" != "$HEAD_COMMIT" ]; then
+      echo "Tag ${RELEASE_TAG} already exists at ${CURRENT_COMMIT}, but HEAD is ${HEAD_COMMIT}." >&2
+      exit 1
+    fi
+    echo "Tag exists at HEAD: ${RELEASE_TAG}"
+  else
+    echo "Creating tag ${RELEASE_TAG}"
+    run git tag -a "$RELEASE_TAG" -m "toolbox ${RELEASE_TAG}"
+  fi
+
+  if [ "$SKIP_GIT_PUSH" -eq 0 ]; then
+    run git push "$REMOTE" HEAD
+    run git push "$REMOTE" "$RELEASE_TAG"
+  fi
+fi
+
+if [ "$SKIP_PUBLISH" -eq 0 ]; then
+  TOKEN="${GITEA_TOKEN:-}"
+  if [ -z "$TOKEN" ]; then
+    if [ -f "${HOME}/.config/gitea/gitea.env" ]; then
+      # shellcheck disable=SC1091
+      . "${HOME}/.config/gitea/gitea.env"
+      TOKEN="${GITEA_TOKEN:-}"
+    fi
+  fi
+
+  if [ -z "$TOKEN" ]; then
+    echo "GITEA_TOKEN is required for publishing (or use --skip-publish)." >&2
+    exit 1
+  fi
+
+  run node scripts/publish-release.mjs \
+    --api-base "$API_BASE" \
+    --owner "$OWNER" \
+    --repo "$REPO" \
+    --tag "$RELEASE_TAG" \
+    --target "$(git rev-parse HEAD)" \
+    --name "Toolbox ${RELEASE_TAG}" \
+    --archive "$ZIP_FILE" \
+    --checksum "$CHECKSUM_FILE" \
+    --lock-file "$LOCK_FILE" \
+    --token "$TOKEN"
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "Dry run complete. No assets were uploaded." 
+  else
+    echo "Published ${RELEASE_TAG} to Gitea." 
+  fi
+fi
+
+echo "Release wrapper finished for ${RELEASE_TAG}" 

scripts/update-release-lock.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { parseReleaseLock } from './release-lock.mjs';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const HEX_HASH = /^[a-f0-9]{64}$/;
+
+function usage() {
+  return `Usage: node scripts/update-release-lock.mjs --app-id ID --app-version VERSION --artifact URL --sha256 HEX --release-version SEMVER [options]
+
+Options:
+  --lock PATH               Path to release lock (default: release/toolbox.lock.json)
+  --portal-version SEMVER   Optional portal package override
+  --app-id ID               App id in lock (for example de.add-ideas.translator-tools)
+  --app-version VERSION     App semantic version
+  --artifact URL            Artifact URL/path/file: URL
+  --sha256 HEX              Optional artifact checksum; required for remote artifacts
+  --release-version VERSION New toolbox release version
+  --assemble                Run npm run build and npm run assemble after patching
+  --force                   Pass --force to assemble command
+  --help                    Show this message
+`;
+}
+
+function parseArguments(argv) {
+  if (argv.includes('--help')) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  const args = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const option = argv[index];
+    if (!option.startsWith('--')) {
+      throw new Error(`Unknown argument: ${option}`);
+    }
+
+    if (option === '--assemble' || option === '--force') {
+      args.set(option, true);
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`${option} requires a value.`);
+    }
+    args.set(option, value);
+    index += 1;
+  }
+
+  return {
+    lockFile: args.get('--lock') ?? 'release/toolbox.lock.json',
+    appId: args.get('--app-id'),
+    appVersion: args.get('--app-version'),
+    artifact: args.get('--artifact'),
+    sha256: args.get('--sha256'),
+    releaseVersion: args.get('--release-version'),
+    portalVersion: args.get('--portal-version'),
+    assemble: args.get('--assemble') === true,
+    forceAssemble: args.get('--force') === true,
+  };
+}
+
+function bumpPatch(version) {
+  const [major, minor, patchAndSuffix] = version.split('.');
+  const [patch] = patchAndSuffix.split('-');
+  const nextPatch = Number.parseInt(patch, 10) + 1;
+  return `${major}.${minor}.${nextPatch}`;
+}
+
+async function sha256ForPath(filePath) {
+  await access(filePath);
+  const hash = createHash('sha256');
+  const input = createReadStream(filePath);
+  await new Promise((resolve, reject) => {
+    input.on('data', (chunk) => hash.update(chunk));
+    input.on('error', reject);
+    input.on('end', resolve);
+  });
+  return hash.digest('hex');
+}
+
+async function computeRemoteSha256(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Unable to download artifact (${response.status} ${response.statusText}).`);
+  }
+
+  if (!response.body) {
+    throw new Error('Artifact download did not provide a response body.');
+  }
+
+  const hash = createHash('sha256');
+  const reader = response.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    hash.update(Buffer.from(value));
+  }
+  return hash.digest('hex');
+}
+
+function resolveArtifactPath(artifact, lockDirectory) {
+  if (/^file:/i.test(artifact)) return new URL(artifact).pathname;
+  if (/^https?:/i.test(artifact)) return null;
+  return path.resolve(lockDirectory, artifact);
+}
+
+function toShaIfNeeded(hash) {
+  if (!hash) return null;
+  const normalized = hash.toLowerCase();
+  if (!HEX_HASH.test(normalized)) {
+    throw new Error('Provided --sha256 is not a valid 64 hex hash.');
+  }
+  return normalized;
+}
+
+function command(cwd) {
+  return (name, args) =>
+    new Promise((resolve, reject) => {
+      const child = spawn(name, args, {
+        cwd,
+        stdio: 'inherit',
+        shell: true,
+      });
+
+      child.on('error', reject);
+      child.on('exit', (code) =>
+        code === 0
+          ? resolve(undefined)
+          : reject(new Error(`${name} ${args.join(' ')} failed with code ${code}`))
+      );
+    });
+}
+
+async function run() {
+  const options = parseArguments(process.argv.slice(2));
+  if (
+    !options.appId ||
+    !options.appVersion ||
+    !options.artifact ||
+    !options.releaseVersion
+  ) {
+    throw new Error(`Missing required options.
+
+${usage()}`);
+  }
+  if (!SEMVER.test(options.releaseVersion)) {
+    throw new Error(`--release-version must be semver: ${options.releaseVersion}`);
+  }
+  if (!SEMVER.test(options.appVersion)) {
+    throw new Error(`--app-version must be semver: ${options.appVersion}`);
+  }
+
+  const lockPath = path.resolve(options.lockFile);
+  const lockDir = path.dirname(lockPath);
+  const lockJson = JSON.parse(await readFile(lockPath, 'utf8'));
+  const lock = parseReleaseLock(lockJson);
+  const nextReleaseVersion = options.releaseVersion ?? bumpPatch(lock.releaseVersion);
+  if (!SEMVER.test(nextReleaseVersion)) {
+    throw new Error(`Invalid release version: ${nextReleaseVersion}`);
+  }
+
+  const appIndex = lock.apps.findIndex((app) => app.id === options.appId);
+  if (appIndex < 0) {
+    throw new Error(`App id not found in lock: ${options.appId}`);
+  }
+
+  const artifactPath = resolveArtifactPath(options.artifact, lockDir);
+  let sha256 = toShaIfNeeded(options.sha256);
+  if (!sha256) {
+    if (artifactPath) {
+      sha256 = await sha256ForPath(artifactPath);
+    } else {
+      sha256 = await computeRemoteSha256(options.artifact);
+    }
+  }
+  if (!HEX_HASH.test(sha256)) {
+    throw new Error('Computed checksum is malformed.');
+  }
+
+  const updatedApps = [...lock.apps];
+  const previous = updatedApps[appIndex];
+  updatedApps[appIndex] = {
+    ...previous,
+    version: options.appVersion,
+    artifact: options.artifact,
+    sha256,
+  };
+
+  const nextLock = {
+    ...lock,
+    releaseVersion: nextReleaseVersion,
+    apps: updatedApps,
+  };
+  if (options.portalVersion) {
+    if (!SEMVER.test(options.portalVersion))
+      throw new Error(`--portal-version must be semver: ${options.portalVersion}`);
+    nextLock.portalVersion = options.portalVersion;
+  }
+
+  parseReleaseLock(nextLock);
+  await writeFile(lockPath, `${JSON.stringify(nextLock, null, 2)}\n`, 'utf8');
+  console.log(`Updated ${path.relative(process.cwd(), lockPath)} (${options.appId})`);
+
+  if (!options.assemble) return;
+  const runCommand = command(process.cwd());
+  await runCommand('npm', ['run', 'build']);
+  const archive = `build/add-ideas-toolbox-${nextReleaseVersion}.zip`;
+  const assembleArgs = [
+    'run',
+    'assemble',
+    '--',
+    '--lock',
+    options.lockFile,
+    '--portal-dist',
+    'dist',
+    '--output',
+    'build/toolbox',
+    '--archive',
+    archive,
+  ];
+  if (options.forceAssemble) assembleArgs.push('--force');
+  await runCommand('npm', assembleArgs);
+  console.log(`Assembled release -> ${archive}`);
+  const releaseChecksum = path.join(
+    path.dirname(archive),
+    `${path.basename(archive)}.sha256`
+  );
+  const releaseSha256 = await sha256ForPath(releaseChecksum === undefined ? '' : releaseChecksum);
+  console.log(`Release checksum: ${releaseSha256}`);
+}
+
+run().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});