envprism 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Titus Kirch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+
+# 🔻 envprism
+
+**One set of variables, refracted into many environment views — a TUI for managing `.env*` files side by side**
+
+![envprism TUI preview](.github/assets/envprism-tui.gif)
+
+</div>
+
+---
+
+```bash
+bunx envprism
+```
+
+That's it. Point `envprism` at a directory containing `.env*` files and it opens a side-by-side matrix view: rows are variable keys, columns are files. Differences light up, missing keys are obvious, and you can edit cells in place — comments, blank lines, and key order survive the round trip.
+
+> [!IMPORTANT]
+> `envprism` runs on **[Bun](https://bun.sh/)** 1.3+. The TUI is powered by [opentui](https://opentui.com/), which links to a native Zig core via `bun:ffi`. Node has no equivalent built-in FFI, so `npx envprism` will not work — install Bun first.
+
+## ✨ Features
+
+### Discovery & comparison
+
+- **🔍 Auto-discovery** — finds every `.env*` file in the current directory (or in `--paths a b c`); skips editor swap files and backups.
+- **🧮 Matrix view** — rows are the union of every variable, columns are the files; the prism metaphor, literal.
+- **🎯 Smart base resolution** — `.env.example` is auto-promoted to base if present, otherwise the alphabetically-first file. Override with `--base file`.
+- **🎨 Per-cell diff icons** — `≠` value differs (yellow), `✗ missing` (red), `★` extra (key not in base, yellow), `⚠` placeholder (orange) — only the icon is coloured, values stay neutral.
+- **🙈 Secret masking** — keys whose name contains `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, `PRIVATE`, … render as `•••• (N)`; allow-list for `PUBLIC_*` and `*_ID`.
+- **🕵️ Placeholder detection** — values like `TODO`, `FIXME`, `CHANGEME`, `xxx`, `your_secret_here`, `replace_me` flag a `⚠` so you know a secret was never filled in.
+- **📂 Section grouping** — comment banners like `# === Database ===` (inline or three-line block, with `=`, `-`, `~`, `*`, or `#` separators) become section dividers; `g` toggles to grouping by key prefix (`APP_*`, `DB_*`).
+- **🪗 Collapsible sections** — `c` folds the focused section; section dividers show drift count (`✗ 2 missing · ≠ 3/5 drift`) so you scan the worst groups first; `Shift-C` expands all.
+- **🔎 Live filter** — `/` opens a popover that filters keys by substring, with a `matching N of M` counter.
+- **🛣️ Drift-only view** — `v` hides keys that already agree with the base, so only the work-to-do remains.
+
+### Editing & write-back
+
+- **✏️ Edit-or-add** — `e` / `Enter` opens an edit popover on any cell; if the key isn't in that file yet, save creates it. The popover renders every file's current value as context next to the input.
+- **➕ Add variable** — `a` walks key + value across two prompts; the parser's `[A-Za-z_][A-Za-z0-9_]*` rule guards the key name.
+- **➖ Delete variable** — `d` removes the focused key from the focused file.
+- **🆕 New `.env*` file** — `n` scaffolds a new file next to the base; saved with the rest on `Ctrl-S`.
+- **🔁 Sync-to-all** — `=` copies the focused cell's value into every file (create or update); `Ctrl-A` inside the edit popover applies what you're typing to every file at once.
+- **🟢 Modified marker** — every cell you touch this session gets a green `●`; clears on save so unsaved local work stands out from "this file just disagrees with base".
+- **↩️ Undo** — `Ctrl-Z` walks back the last 50 edits / adds / deletes.
+- **💾 Save** — `Ctrl-S` writes every dirty file. **Round-trip preserving**: comments, blank lines, key order, quoting, `export ` prefixes, and inline `#` comments survive byte-for-byte — only the keys you changed are rewritten.
+- **⚠️ Quit guard** — `q` asks once before quitting if you have unsaved changes; `Ctrl-C` always force-quits.
+
+### Navigation & panes
+
+- **🧭 Two panes** — `Tab` switches between the matrix and the files sidebar; arrow-left at the leftmost matrix column hops into the sidebar.
+- **☑️ Enable / disable files** — `Space` in the sidebar drops a file out of the matrix (without deleting from disk); `b` promotes the selected file to base (auto-enables it if disabled).
+- **🖱️ Mouse** — wheel scrolls the matrix in both axes; the focused cell auto-scrolls into view when you reach the viewport edge.
+- **❓ Help overlay** — `?` (or `ß` for QWERTZ) opens a keybinding reference; renders as a two-column grid on wide terminals and a single scrollable column on narrow / short ones.
+
+### CI & scripting
+
+- **🧪 `envprism diff`** — non-interactive subcommand that prints a text drift table, JSON (`--json`), or just sets the exit code (`--check`). Drop it into a pre-commit hook or CI to fail builds that drift from `.env.example`.
+
+## 📦 Installation
+
+Install Bun (one-time): see [bun.sh](https://bun.sh/).
+
+```bash
+bun add -g envprism
+```
+
+Or run without installing:
+
+```bash
+bunx envprism
+```
+
+Requirements: **Bun 1.3+**.
+
+## 🚀 Quick start
+
+```bash
+bunx envprism                      # open the TUI in the current directory
+bunx envprism tui path/to/repo     # TUI scanning another directory
+bunx envprism diff path/to/repo    # non-interactive drift report
+bunx envprism diff --json | jq     # structured drift report
+bunx envprism diff --check; echo $?  # exits 1 if any file drifts from base
+```
+
+Inside the TUI, press `?` for the full keybinding reference.
+
+## 🤝 Contributing
+
+PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs the project's linters/formatters on `git commit`.
+
+> [!TIP]
+> Run `pnpm check:fix` before pushing — CI will catch what husky missed.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## 🛣️ Versioning
+
+[Semantic Versioning](https://semver.org/) via [release-please](https://github.com/googleapis/release-please) — see [CHANGELOG.md](CHANGELOG.md).
+
+## 📄 License
+
+[MIT](LICENSE) © [Titus Kirch](https://github.com/TitusKirch/) / [IT-Dienstleistungen Titus Kirch](https://kirch.dev)

package/dist/bin/envprism.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+import consola from "consola";
+import { resolve } from "pathe";
+import { d as discoverEnvFiles, r as resolveBase, b as buildMatrix, c as computeDiff, f as formatDiffText } from "../chunks/matrix-nBq_GY2v.mjs";
+const diffCommand = defineCommand({
+  meta: {
+    name: "diff",
+    description: "Print the drift between .env* files compared to a base."
+  },
+  args: {
+    paths: {
+      type: "positional",
+      required: false,
+      description: "Directory or files to scan (defaults to cwd)."
+    },
+    base: {
+      type: "string",
+      description: "Base file to diff against (defaults to .env.example)."
+    },
+    json: {
+      type: "boolean",
+      description: "Emit JSON instead of a text table."
+    },
+    check: {
+      type: "boolean",
+      description: "Suppress output and exit 1 when any file drifts from the base."
+    }
+  },
+  async run({ args }) {
+    const inputs = collectPaths$1(args.paths);
+    const files = await discoverEnvFiles(inputs.map((p) => resolve(p)));
+    if (files.length === 0) {
+      if (!args.check) consola.warn("No .env* files found.");
+      process.exit(args.check ? 0 : 1);
+    }
+    const base = resolveBase(files, args.base);
+    if (!base) {
+      consola.error("Could not resolve a base file.");
+      process.exit(1);
+    }
+    const matrix = buildMatrix(files, base);
+    const report = computeDiff(matrix);
+    if (args.check) {
+      process.exit(report.inSync ? 0 : 1);
+    }
+    if (args.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+      return;
+    }
+    process.stdout.write(formatDiffText(report));
+  }
+});
+function collectPaths$1(arg) {
+  if (Array.isArray(arg)) return arg.map(String);
+  if (typeof arg === "string" && arg.length > 0) return [arg];
+  return ["."];
+}
+async function runTui(args) {
+  const inputs = collectPaths(args.paths);
+  const files = await discoverEnvFiles(inputs.map((p) => resolve(p)));
+  if (files.length === 0) {
+    consola.warn("No .env* files found.");
+    process.exit(1);
+  }
+  const base = resolveBase(files, args.base);
+  if (!base) {
+    consola.error("Could not resolve a base file.");
+    process.exit(1);
+  }
+  const matrix = buildMatrix(files, base);
+  const { runMatrixTui } = await import("../chunks/app-d_wGTwvJ.mjs");
+  await runMatrixTui(matrix);
+}
+const tuiCommand = defineCommand({
+  meta: {
+    name: "tui",
+    description: "Open the interactive matrix view (default command)."
+  },
+  args: {
+    paths: {
+      type: "positional",
+      required: false,
+      description: "Directory or files to scan (defaults to cwd)."
+    },
+    base: {
+      type: "string",
+      description: "Base file to diff against (defaults to .env.example)."
+    }
+  },
+  async run({ args }) {
+    await runTui({ paths: args.paths, base: args.base });
+  }
+});
+function collectPaths(arg) {
+  if (Array.isArray(arg)) return arg.map(String);
+  if (typeof arg === "string" && arg.length > 0) return [arg];
+  return ["."];
+}
+const SUBCOMMANDS = /* @__PURE__ */ new Set(["tui", "diff"]);
+const rootCommand = defineCommand({
+  meta: {
+    name: "envprism",
+    description: "TUI-based env file manager — refract one set of variables into many environment views."
+  },
+  subCommands: {
+    tui: tuiCommand,
+    diff: diffCommand
+  },
+  // citty 0.1.6 invokes the root `run` after a matched subcommand returns,
+  // so guard against double-execution by bailing when the first positional
+  // arg names a known subcommand. With no args at all we launch the TUI in
+  // the cwd, which is the documented default.
+  async run({ rawArgs }) {
+    const firstPositional = rawArgs.find((a) => !a.startsWith("-"));
+    if (firstPositional && SUBCOMMANDS.has(firstPositional)) return;
+    await runTui({});
+  }
+});
+runMain(rootCommand);
+//# sourceMappingURL=envprism.mjs.map

package/dist/bin/envprism.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"envprism.mjs","sources":["../../src/commands/diff.ts","../../src/commands/tui.ts","../../src/cli.ts","../../src/bin/envprism.ts"],"sourcesContent":["import { defineCommand } from 'citty';\nimport consola from 'consola';\nimport { resolve } from 'pathe';\nimport { resolveBase } from '../core/base.ts';\nimport { computeDiff, formatDiffText } from '../core/diff.ts';\nimport { discoverEnvFiles } from '../core/discover.ts';\nimport { buildMatrix } from '../core/matrix.ts';\n\nexport const diffCommand = defineCommand({\n  meta: {\n    name: 'diff',\n    description: 'Print the drift between .env* files compared to a base.'\n  },\n  args: {\n    paths: {\n      type: 'positional',\n      required: false,\n      description: 'Directory or files to scan (defaults to cwd).'\n    },\n    base: {\n      type: 'string',\n      description: 'Base file to diff against (defaults to .env.example).'\n    },\n    json: {\n      type: 'boolean',\n      description: 'Emit JSON instead of a text table.'\n    },\n    check: {\n      type: 'boolean',\n      description:\n        'Suppress output and exit 1 when any file drifts from the base.'\n    }\n  },\n  async run({ args }) {\n    const inputs = collectPaths(args.paths);\n    const files = await discoverEnvFiles(inputs.map((p) => resolve(p)));\n\n    if (files.length === 0) {\n      if (!args.check) consola.warn('No .env* files found.');\n      process.exit(args.check ? 0 : 1);\n    }\n\n    const base = resolveBase(files, args.base);\n    if (!base) {\n      consola.error('Could not resolve a base file.');\n      process.exit(1);\n    }\n\n    const matrix = buildMatrix(files, base);\n    const report = computeDiff(matrix);\n\n    if (args.check) {\n      process.exit(report.inSync ? 0 : 1);\n    }\n\n    if (args.json) {\n      process.stdout.write(JSON.stringify(report, null, 2) + '\\n');\n      return;\n    }\n\n    process.stdout.write(formatDiffText(report));\n  }\n});\n\nfunction collectPaths(arg: unknown): string[] {\n  if (Array.isArray(arg)) return arg.map(String);\n  if (typeof arg === 'string' && arg.length > 0) return [arg];\n  return ['.'];\n}\n","import { defineCommand } from 'citty';\nimport consola from 'consola';\nimport { resolve } from 'pathe';\nimport { resolveBase } from '../core/base.ts';\nimport { discoverEnvFiles } from '../core/discover.ts';\nimport { buildMatrix } from '../core/matrix.ts';\n\ninterface TuiInvocation {\n  paths?: string | string[];\n  base?: string;\n}\n\n/**\n * Resolve the matrix and boot the TUI. Shared between the explicit `tui`\n * subcommand and the default-no-subcommand path in `rootCommand`.\n */\nexport async function runTui(args: TuiInvocation): Promise<void> {\n  const inputs = collectPaths(args.paths);\n  const files = await discoverEnvFiles(inputs.map((p) => resolve(p)));\n\n  if (files.length === 0) {\n    consola.warn('No .env* files found.');\n    process.exit(1);\n  }\n\n  const base = resolveBase(files, args.base);\n  if (!base) {\n    consola.error('Could not resolve a base file.');\n    process.exit(1);\n  }\n\n  const matrix = buildMatrix(files, base);\n\n  // Dynamic import keeps @opentui/core out of the bundle path used by the\n  // `diff` subcommand, so users running diff on Node never hit Bun-only code.\n  const { runMatrixTui } = await import('../tui/app.ts');\n  await runMatrixTui(matrix);\n}\n\nexport const tuiCommand = defineCommand({\n  meta: {\n    name: 'tui',\n    description: 'Open the interactive matrix view (default command).'\n  },\n  args: {\n    paths: {\n      type: 'positional',\n      required: false,\n      description: 'Directory or files to scan (defaults to cwd).'\n    },\n    base: {\n      type: 'string',\n      description: 'Base file to diff against (defaults to .env.example).'\n    }\n  },\n  async run({ args }) {\n    await runTui({ paths: args.paths, base: args.base });\n  }\n});\n\nfunction collectPaths(arg: unknown): string[] {\n  if (Array.isArray(arg)) return arg.map(String);\n  if (typeof arg === 'string' && arg.length > 0) return [arg];\n  return ['.'];\n}\n","import { defineCommand } from 'citty';\nimport { diffCommand } from './commands/diff.ts';\nimport { runTui, tuiCommand } from './commands/tui.ts';\n\nconst SUBCOMMANDS = new Set(['tui', 'diff']);\n\nexport const rootCommand = defineCommand({\n  meta: {\n    name: 'envprism',\n    description:\n      'TUI-based env file manager — refract one set of variables into many environment views.'\n  },\n  subCommands: {\n    tui: tuiCommand,\n    diff: diffCommand\n  },\n  // citty 0.1.6 invokes the root `run` after a matched subcommand returns,\n  // so guard against double-execution by bailing when the first positional\n  // arg names a known subcommand. With no args at all we launch the TUI in\n  // the cwd, which is the documented default.\n  async run({ rawArgs }) {\n    const firstPositional = rawArgs.find((a) => !a.startsWith('-'));\n    if (firstPositional && SUBCOMMANDS.has(firstPositional)) return;\n    await runTui({});\n  }\n});\n","import { runMain } from 'citty';\nimport { rootCommand } from '../cli.ts';\n\nrunMain(rootCommand);\n"],"names":["collectPaths"],"mappings":"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"}