From a5b9fc0cf72fa030a92b2d5c49d9526e0b49f7e9 Mon Sep 17 00:00:00 2001 From: MrSphay Date: Sat, 2 May 2026 00:10:52 +0200 Subject: [PATCH] Switch repository docs to English README workflow --- README.md | 179 +++++++++++++++++++++---------------- blueprint.json | 33 +++++++ blueprint.md | 238 +++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 3 +- src/App.tsx | 9 +- 5 files changed, 384 insertions(+), 78 deletions(-) create mode 100644 blueprint.json create mode 100644 blueprint.md diff --git a/README.md b/README.md index e47c838..9c31fbd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

EnvHelper

- Lokale Windows-App zum sauberen Ausfuellen von .env-Vorlagen. + A local Windows desktop app for turning .env templates into deployable configuration files.

@@ -14,67 +14,68 @@ --- -## Inhalt +## Table of Contents -- [Kurzbeschreibung](#kurzbeschreibung) +- [Overview](#overview) - [Features](#features) - [Workflow](#workflow) -- [Beispiel](#beispiel) -- [Erkennung](#erkennung) -- [Standardwerte](#standardwerte) -- [Download und Artefakte](#download-und-artefakte) -- [Entwicklung](#entwicklung) +- [Example](#example) +- [Placeholder Detection](#placeholder-detection) +- [Default Values](#default-values) +- [Downloads and Artifacts](#downloads-and-artifacts) +- [Development](#development) - [Windows Build](#windows-build) -- [Sicherheit](#sicherheit) -- [Projektinfos](#projektinfos) +- [README Generation](#readme-generation) +- [Security](#security) +- [Project Info](#project-info) --- -## Kurzbeschreibung +## Overview -EnvHelper liest `.env`-Dateien oder reinen Text ein, erkennt `CHANGE_ME`-Platzhalter und erzeugt passende Werte im erwarteten Format. Gleiche Platzhalter erhalten denselben Wert, damit zusammenhaengende Variablen wie `DATABASE_URL` und `POSTGRES_PASSWORD` synchron bleiben. +EnvHelper reads `.env` files or plain text, detects `CHANGE_ME` placeholders, infers the required value format, and produces a ready-to-use output file. Identical placeholders are replaced with the same generated value, so related variables such as `DATABASE_URL` and `POSTGRES_PASSWORD` stay in sync. -Die App arbeitet lokal als Desktop-Tool. Es werden keine Secrets an externe Dienste gesendet. +The app is local-first. It does not send generated secrets or input files to external services. --- ## Features -| Bereich | Beschreibung | +| Area | Description | | --- | --- | -| Datei und Text | `.env` laden, Text direkt einfuegen, Ergebnis kopieren oder speichern | -| Placeholder | Erkennt `CHANGE_ME...` Werte und ersetzt sie formatbewusst | -| Konsistenz | Gleiche Placeholder werden im gesamten Output identisch ersetzt | -| Formate | Passwoerter, Secrets, Base64, Hex, UUID, Ports, URLs, E-Mail, API-Key-Praefixe | -| Standardwerte | Erkennt naheliegende Defaults automatisch und erlaubt manuelle Overrides | -| Desktop UI | Kompakte Windows-App mit nativer Fensterleiste, Darkmode und Settings | -| Sprachen | Deutsch, Englisch, Spanisch, Franzoesisch, Niederlaendisch | -| Build | Windows Setup und Portable EXE ueber Gitea Runner | +| File and text input | Load `.env` files, paste text directly, copy output, or save a new `.env` | +| Placeholder replacement | Detects `CHANGE_ME...` values and replaces them with format-aware values | +| Consistency | Reuses the same generated value for repeated placeholders | +| Supported formats | Passwords, secrets, Base64, hex, UUIDs, ports, URLs, email addresses, and API key prefixes | +| Default values | Detects likely defaults automatically and allows manual overrides | +| Desktop UI | Compact Windows app with a native title bar, dark mode, and settings | +| Languages | German, English, Spanish, French, and Dutch | +| Build output | Windows setup and portable executables via Gitea Runner | --- ## Workflow ```text -1. .env Datei laden oder Text einfuegen -2. Automatische Standardwerte pruefen oder eigene Defaults ergaenzen -3. CHANGE_ME Platzhalter generieren lassen -4. Output kopieren oder als neue .env speichern +1. Load a .env file or paste text. +2. Review automatically detected defaults or add your own. +3. Generate values for CHANGE_ME placeholders. +4. Copy the output or save it as a new .env file. ``` ```text -Input Verarbeitung Output ------ ------------ ------ -DATABASE_URL=... Placeholder erkennen DATABASE_URL=... -POSTGRES_PASSWORD=... -> Format ableiten -> POSTGRES_PASSWORD=... -SESSION_SECRET=... Werte lokal erzeugen SESSION_SECRET=... +Input Processing Output +----- ---------- ------ +DATABASE_URL=... Detect placeholders DATABASE_URL=... +POSTGRES_PASSWORD=... -> Infer formats -> POSTGRES_PASSWORD=... +SESSION_SECRET=... Generate local values SESSION_SECRET=... ``` --- -## Beispiel +## Example -Eingabe: +Input: ```env APP_PORT=3000 @@ -90,7 +91,7 @@ BOOTSTRAP_ADMIN_EMAIL=CHANGE_ME_EMAIL BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_LONG_INITIAL_ADMIN_PASSWORD ``` -Moeglicher Output: +Possible output: ```env APP_PORT=3000 @@ -106,35 +107,35 @@ BOOTSTRAP_ADMIN_EMAIL=admin@example.local BOOTSTRAP_ADMIN_PASSWORD=Wz4...strongPassword ``` -Die echten Werte werden zufaellig lokal erzeugt. +The actual values are generated randomly on the local machine. --- -## Erkennung +## Placeholder Detection -EnvHelper priorisiert den Inhalt des Platzhalters vor dem umgebenden Variablennamen. Dadurch wird zum Beispiel `CHANGE_ME_POSTGRES_PASSWORD` innerhalb einer `DATABASE_URL` als Passwort erkannt und nicht faelschlich als URL. +EnvHelper prioritizes the placeholder text over the surrounding variable name. This prevents cases such as `CHANGE_ME_POSTGRES_PASSWORD` inside `DATABASE_URL` from being misclassified as a URL. -Unterstuetzte Muster sind unter anderem: +Supported examples: -| Muster | Ergebnis | +| Pattern | Result | | --- | --- | -| `CHANGE_ME_POSTGRES_PASSWORD` | starkes URL-sicheres Passwort | -| `CHANGE_ME_32_RANDOM_BYTES_AS_BASE64` | 32 zufaellige Bytes als Base64 | -| `CHANGE_ME_HEX_TOKEN` | zufaellige Bytes als Hex | +| `CHANGE_ME_POSTGRES_PASSWORD` | Strong URL-safe password | +| `CHANGE_ME_32_RANDOM_BYTES_AS_BASE64` | 32 random bytes encoded as Base64 | +| `CHANGE_ME_HEX_TOKEN` | Random bytes encoded as hex | | `CHANGE_ME_UUID` | UUID v4 | | `CHANGE_ME_PUBLIC_URL` | HTTPS URL | -| `CHANGE_ME_EMAIL` | E-Mail-Adresse | -| `STRIPE_SECRET_KEY=CHANGE_ME` | Stripe-artiger `sk_test_...` Wert | -| `STRIPE_WEBHOOK_SECRET=CHANGE_ME` | Stripe-artiger `whsec_...` Wert | -| `AWS_ACCESS_KEY_ID=CHANGE_ME` | AWS/S3-artiges Access-Key-ID Format | +| `CHANGE_ME_EMAIL` | Email address | +| `STRIPE_SECRET_KEY=CHANGE_ME` | Stripe-like `sk_test_...` value | +| `STRIPE_WEBHOOK_SECRET=CHANGE_ME` | Stripe-like `whsec_...` value | +| `AWS_ACCESS_KEY_ID=CHANGE_ME` | AWS/S3-like access key ID format | -Weitere Heuristiken decken typische `.env.example`-Variablen fuer SMTP, S3/MinIO, Redis, RabbitMQ, CORS, Log-Level, Environment-Flags und API Keys ab. +Additional heuristics cover common `.env.example` variables for SMTP, S3/MinIO, Redis, RabbitMQ, CORS, log levels, environment flags, and API keys. --- -## Standardwerte +## Default Values -Standardwerte werden in einer eigenen Sektion angezeigt. Die App erkennt naheliegende Defaults automatisch, zum Beispiel: +Default values are shown in their own section. EnvHelper detects likely defaults automatically, for example: | Key | Default | | --- | --- | @@ -145,37 +146,44 @@ Standardwerte werden in einer eigenen Sektion angezeigt. Die App erkennt nahelie | `S3_REGION` | `eu-central-1` | | `REDIS_URL` | `redis://redis:6379/0` | -Manuelle Defaults koennen jederzeit hinzugefuegt werden. Sie ueberschreiben automatisch erkannte Defaults und wirken nur auf den Output, nicht auf die Eingabevorlage. +Manual defaults can always be added. They override automatically detected defaults and only affect the output, never the input template. --- -## Download und Artefakte +## Downloads and Artifacts -Der Windows-Build erzeugt zwei nutzbare Dateien: +The Windows build produces two executable artifacts: ```text EnvHelper-0.1.0-setup-x64.exe EnvHelper-0.1.0-portable-x64.exe ``` -Die Dateien werden vom Gitea Runner als Actions-Artefakt und als Generic Package veroeffentlicht. +The files are published by the Gitea Runner as an Actions artifact and as a Generic Package. --- -## Entwicklung +## Development + +Install dependencies: ```bash npm install +``` + +Start the Vite development server: + +```bash npm run dev ``` -Build pruefen: +Check the production build: ```bash npm run build ``` -Windows-Paket lokal bauen: +Build Windows packages: ```bash npm run dist:win @@ -185,48 +193,69 @@ npm run dist:win ## Windows Build -Der produktive Windows-Build laeuft ueber Gitea Actions: +The production Windows build runs through Gitea Actions: ```text .gitea/workflows/build-windows.yml ``` -Der Runner: +The runner: -1. checkt das Repository aus, -2. installiert Node.js, -3. installiert Wine fuer Windows-Packaging auf Linux, -4. baut Vite, TypeScript und Electron, -5. erzeugt Setup und Portable EXE, -6. laedt Artefakte und Packages nach Gitea hoch. +1. checks out the repository, +2. installs Node.js, +3. installs Wine for Windows packaging on Linux, +4. builds Vite, TypeScript, and Electron, +5. creates setup and portable executables, +6. uploads artifacts and packages to Gitea. --- -## Sicherheit +## README Generation -EnvHelper erzeugt Werte lokal im Renderer mit Web-Crypto. Die App ist ein Helfer fuer `.env`-Vorlagen und ersetzt keine zentrale Secret-Verwaltung fuer produktive Infrastruktur. +The README structure follows the blueprint-based workflow from [`andreasbm/readme`](https://github.com/andreasbm/readme). -### Windows Defender und SmartScreen +Source files: -Windows kann Apps mit unbekanntem Herausgeber blockieren oder verzoegert starten. Das liegt normalerweise an fehlender Reputation oder fehlendem vertrauenswuerdigem Code-Signing-Zertifikat. +```text +blueprint.md +blueprint.json +``` -Der Workflow ist fuer Code Signing vorbereitet: +Regenerate the README with: + +```bash +npm run readme +``` + +The generated output is committed as `README.md` so Gitea can render it directly without any additional tooling. + +--- + +## Security + +EnvHelper generates values locally in the renderer using Web Crypto. It is a helper for `.env` templates and is not a replacement for a central secret manager in production infrastructure. + +### Windows Defender and SmartScreen + +Windows may block or delay apps from unknown publishers. This is usually caused by missing reputation or by the absence of a trusted code-signing certificate. + +The workflow is prepared for code signing: ```text WINDOWS_CSC_LINK WINDOWS_CSC_KEY_PASSWORD ``` -`WINDOWS_CSC_LINK` ist das Zertifikat, zum Beispiel als Base64-kodierte `.pfx` Datei oder als erreichbare Zertifikats-URL. `WINDOWS_CSC_KEY_PASSWORD` ist das Passwort des Zertifikats. +`WINDOWS_CSC_LINK` is the certificate, for example a Base64-encoded `.pfx` file or a reachable certificate URL. `WINDOWS_CSC_KEY_PASSWORD` is the certificate password. --- -## Projektinfos +## Project Info -| Feld | Wert | +| Field | Value | | --- | --- | -| Autor | `MrSphay` | +| Author | `MrSphay` | | Repository | `MrSphay/envHelper` | -| App-ID | `de.wilkensxl.envhelper` | +| App ID | `de.wilkensxl.envhelper` | | Stack | Electron, React, Vite, TypeScript | -| README-Stil | Inspiriert von `andreasbm/readme` | +| README workflow | Blueprint-inspired workflow based on `andreasbm/readme` | diff --git a/blueprint.json b/blueprint.json new file mode 100644 index 0000000..1add75d --- /dev/null +++ b/blueprint.json @@ -0,0 +1,33 @@ +{ + "ids": { + "github": "MrSphay/envHelper" + }, + "badges": [ + { + "alt": "Platform", + "img": "https://img.shields.io/badge/platform-Windows-2563eb", + "url": "https://git.wilkensxl.de/MrSphay/envHelper" + }, + { + "alt": "Stack", + "img": "https://img.shields.io/badge/stack-Electron%20%2B%20React%20%2B%20TypeScript-0f766e", + "url": "https://www.electronjs.org/" + }, + { + "alt": "Build", + "img": "https://img.shields.io/badge/build-Gitea%20Runner-a855f7", + "url": "https://docs.gitea.com/usage/actions/overview" + }, + { + "alt": "Version", + "img": "https://img.shields.io/badge/version-0.1.0-111827", + "url": "https://git.wilkensxl.de/MrSphay/envHelper" + } + ], + "headingPrefix": { + "1": "", + "2": "" + }, + "line": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png", + "text": "A local Windows desktop app for turning .env templates into deployable configuration files." +} diff --git a/blueprint.md b/blueprint.md new file mode 100644 index 0000000..77e5bd6 --- /dev/null +++ b/blueprint.md @@ -0,0 +1,238 @@ +{{ template:title }} + +{{ template:badges }} + +--- + +{{ template:table-of-contents }} + +--- + +## Overview + +EnvHelper reads `.env` files or plain text, detects `CHANGE_ME` placeholders, infers the required value format, and produces a ready-to-use output file. Identical placeholders are replaced with the same generated value, so related variables such as `DATABASE_URL` and `POSTGRES_PASSWORD` stay in sync. + +The app is local-first. It does not send generated secrets or input files to external services. + +--- + +## Features + +| Area | Description | +| --- | --- | +| File and text input | Load `.env` files, paste text directly, copy output, or save a new `.env` | +| Placeholder replacement | Detects `CHANGE_ME...` values and replaces them with format-aware values | +| Consistency | Reuses the same generated value for repeated placeholders | +| Supported formats | Passwords, secrets, Base64, hex, UUIDs, ports, URLs, email addresses, and API key prefixes | +| Default values | Detects likely defaults automatically and allows manual overrides | +| Desktop UI | Compact Windows app with a native title bar, dark mode, and settings | +| Languages | German, English, Spanish, French, and Dutch | +| Build output | Windows setup and portable executables via Gitea Runner | + +--- + +## Workflow + +```text +1. Load a .env file or paste text. +2. Review automatically detected defaults or add your own. +3. Generate values for CHANGE_ME placeholders. +4. Copy the output or save it as a new .env file. +``` + +```text +Input Processing Output +----- ---------- ------ +DATABASE_URL=... Detect placeholders DATABASE_URL=... +POSTGRES_PASSWORD=... -> Infer formats -> POSTGRES_PASSWORD=... +SESSION_SECRET=... Generate local values SESSION_SECRET=... +``` + +--- + +## Example + +Input: + +```env +APP_PORT=3000 +NODE_ENV=production +PUBLIC_BASE_URL=CHANGE_ME_PUBLIC_URL + +DATABASE_URL=postgresql://app_user:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/app_db +POSTGRES_PASSWORD=CHANGE_ME_POSTGRES_PASSWORD + +SESSION_SECRET=CHANGE_ME_AT_LEAST_32_RANDOM_CHARACTERS +ENCRYPTION_KEY_BASE64=CHANGE_ME_32_RANDOM_BYTES_AS_BASE64 +BOOTSTRAP_ADMIN_EMAIL=CHANGE_ME_EMAIL +BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_LONG_INITIAL_ADMIN_PASSWORD +``` + +Possible output: + +```env +APP_PORT=3000 +NODE_ENV=production +PUBLIC_BASE_URL=https://example.local + +DATABASE_URL=postgresql://app_user:K2d8rF7s...@postgres:5432/app_db +POSTGRES_PASSWORD=K2d8rF7s... + +SESSION_SECRET=n9pS...urlSafeSecret +ENCRYPTION_KEY_BASE64=4G8t...base64Value +BOOTSTRAP_ADMIN_EMAIL=admin@example.local +BOOTSTRAP_ADMIN_PASSWORD=Wz4...strongPassword +``` + +The actual values are generated randomly on the local machine. + +--- + +## Placeholder Detection + +EnvHelper prioritizes the placeholder text over the surrounding variable name. This prevents cases such as `CHANGE_ME_POSTGRES_PASSWORD` inside `DATABASE_URL` from being misclassified as a URL. + +Supported examples: + +| Pattern | Result | +| --- | --- | +| `CHANGE_ME_POSTGRES_PASSWORD` | Strong URL-safe password | +| `CHANGE_ME_32_RANDOM_BYTES_AS_BASE64` | 32 random bytes encoded as Base64 | +| `CHANGE_ME_HEX_TOKEN` | Random bytes encoded as hex | +| `CHANGE_ME_UUID` | UUID v4 | +| `CHANGE_ME_PUBLIC_URL` | HTTPS URL | +| `CHANGE_ME_EMAIL` | Email address | +| `STRIPE_SECRET_KEY=CHANGE_ME` | Stripe-like `sk_test_...` value | +| `STRIPE_WEBHOOK_SECRET=CHANGE_ME` | Stripe-like `whsec_...` value | +| `AWS_ACCESS_KEY_ID=CHANGE_ME` | AWS/S3-like access key ID format | + +Additional heuristics cover common `.env.example` variables for SMTP, S3/MinIO, Redis, RabbitMQ, CORS, log levels, environment flags, and API keys. + +--- + +## Default Values + +Default values are shown in their own section. EnvHelper detects likely defaults automatically, for example: + +| Key | Default | +| --- | --- | +| `BOOTSTRAP_ADMIN_EMAIL` | `admin@example.local` | +| `NODE_ENV` | `production` | +| `LOG_LEVEL` | `info` | +| `SMTP_PORT` | `587` | +| `S3_REGION` | `eu-central-1` | +| `REDIS_URL` | `redis://redis:6379/0` | + +Manual defaults can always be added. They override automatically detected defaults and only affect the output, never the input template. + +--- + +## Downloads and Artifacts + +The Windows build produces two executable artifacts: + +```text +EnvHelper-0.1.0-setup-x64.exe +EnvHelper-0.1.0-portable-x64.exe +``` + +The files are published by the Gitea Runner as an Actions artifact and as a Generic Package. + +--- + +## Development + +Install dependencies: + +```bash +npm install +``` + +Start the Vite development server: + +```bash +npm run dev +``` + +Check the production build: + +```bash +npm run build +``` + +Build Windows packages: + +```bash +npm run dist:win +``` + +--- + +## Windows Build + +The production Windows build runs through Gitea Actions: + +```text +.gitea/workflows/build-windows.yml +``` + +The runner: + +1. checks out the repository, +2. installs Node.js, +3. installs Wine for Windows packaging on Linux, +4. builds Vite, TypeScript, and Electron, +5. creates setup and portable executables, +6. uploads artifacts and packages to Gitea. + +--- + +## README Generation + +The README structure follows the blueprint-based workflow from [`andreasbm/readme`](https://github.com/andreasbm/readme). + +Source files: + +```text +blueprint.md +blueprint.json +``` + +Regenerate the README with: + +```bash +npm run readme +``` + +The generated output is committed as `README.md` so Gitea can render it directly without any additional tooling. + +--- + +## Security + +EnvHelper generates values locally in the renderer using Web Crypto. It is a helper for `.env` templates and is not a replacement for a central secret manager in production infrastructure. + +### Windows Defender and SmartScreen + +Windows may block or delay apps from unknown publishers. This is usually caused by missing reputation or by the absence of a trusted code-signing certificate. + +The workflow is prepared for code signing: + +```text +WINDOWS_CSC_LINK +WINDOWS_CSC_KEY_PASSWORD +``` + +`WINDOWS_CSC_LINK` is the certificate, for example a Base64-encoded `.pfx` file or a reachable certificate URL. `WINDOWS_CSC_KEY_PASSWORD` is the certificate password. + +--- + +## Project Info + +| Field | Value | +| --- | --- | +| Author | `MrSphay` | +| Repository | `MrSphay/envHelper` | +| App ID | `de.wilkensxl.envhelper` | +| Stack | Electron, React, Vite, TypeScript | +| README workflow | Blueprint-inspired workflow based on `andreasbm/readme` | diff --git a/package.json b/package.json index fcb1107..82654ff 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,8 @@ "dev": "vite --host 127.0.0.1", "build": "tsc --noEmit && vite build && tsc -p tsconfig.electron.json", "dist:win": "npm run build && electron-builder --win nsis portable --x64 --publish never", - "lint": "tsc --noEmit" + "lint": "tsc --noEmit", + "readme": "npx --yes @appnest/readme generate -i blueprint.md -c blueprint.json" }, "dependencies": { "lucide-react": "^0.468.0", diff --git a/src/App.tsx b/src/App.tsx index ba386a8..cc36272 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -54,6 +54,7 @@ const translations = { values: "Werte", defaultsApplied: "Defaults", source: "Quelle", + file: "Datei", text: "Text", defaults: "Standardwerte", defaultsHint: "Mögliche Standardwerte werden erkannt; eigene Werte überschreiben passende Keys im Output.", @@ -93,6 +94,7 @@ const translations = { values: "Values", defaultsApplied: "Defaults", source: "Source", + file: "File", text: "Text", defaults: "Defaults", defaultsHint: "Possible defaults are detected; custom values override matching keys in the output.", @@ -132,6 +134,7 @@ const translations = { values: "Valores", defaultsApplied: "Defaults", source: "Origen", + file: "Archivo", text: "Texto", defaults: "Valores predeterminados", defaultsHint: "Se detectan valores posibles; los personalizados sobrescriben claves iguales.", @@ -171,6 +174,7 @@ const translations = { values: "Valeurs", defaultsApplied: "Défauts", source: "Source", + file: "Fichier", text: "Texte", defaults: "Valeurs par défaut", defaultsHint: "Les valeurs possibles sont détectées; les valeurs personnalisées remplacent les clés.", @@ -210,6 +214,7 @@ const translations = { values: "Waarden", defaultsApplied: "Defaults", source: "Bron", + file: "Bestand", text: "Tekst", defaults: "Standaardwaarden", defaultsHint: "Mogelijke standaardwaarden worden herkend; eigen waarden overschrijven keys.", @@ -244,7 +249,7 @@ function detectLanguage(): Language { } const browserLanguage = navigator.language.slice(0, 2) as Language; - return browserLanguage in languageNames ? browserLanguage : "de"; + return browserLanguage in languageNames ? browserLanguage : "en"; } function readDefaults(): EnvDefault[] { @@ -610,7 +615,7 @@ export default function App() { - +