qwik-envr 0.5.0__tar.gz

qwik_envr-0.5.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.venv-*/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.opencode/
+.env
+.env.*
+.pypirc
+*.log
+.DS_Store

qwik_envr-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Himakar Reddy
+
+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.

qwik_envr-0.5.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: qwik-envr
+Version: 0.5.0
+Summary: A local browser editor for Unix shell environment variables.
+Project-URL: Homepage, https://github.com/Qwik-Tools/envr
+Project-URL: Repository, https://github.com/Qwik-Tools/envr
+Project-URL: Issues, https://github.com/Qwik-Tools/envr/issues
+Author: Himakar Reddy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,environment,secrets,shell,unix
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: BSD
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# envr
+
+Edit shell environment variables in your browser. Run `envr`, and it opens a local
+table for the `export NAME=value` entries in a marked section of your startup file.
+Add, edit, save, or delete entries without dumping the rest of your shell config.
+
+**Package:** `qwik-envr` on PyPI · **Command:** `envr` · **Python:** 3.9+
+
+## Install
+
+```sh
+pipx install qwik-envr
+# or use a virtual environment
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install qwik-envr
+```
+
+The unrelated PyPI package named `envr` is **not** this project. Do not install both
+in the same environment: they may share the `envr` import/command name.
+
+## Quick start
+
+Put two **identical** marker lines in your shell config:
+
+```sh
+##</env secrets>
+export API_KEY='your-value'
+export DATABASE_URL='postgres://localhost/example'
+##</env secrets>
+```
+
+Then run:
+
+```console
+$ envr
+envr: macOS 26.3 (arm64) -- OK
+envr: 2 exports from ~/.zshrc at http://127.0.0.1:49152/<random-token>/
+envr: Ctrl-C to stop
+```
+
+The port and access token are randomly assigned each run. Your default browser
+opens automatically; the server stays running until **Ctrl-C**. Each row has
+**Save** and **Delete** buttons; use **Add** for new variables. Changes save
+immediately. Refresh the page to reload changes made in another editor.
+
+If the startup file is missing, an interactive run asks before creating an empty,
+owner-only file (`0600`, subject to umask). Add the markers yourself afterward.
+Noninteractive runs never prompt or create a file. Missing markers are reported,
+not inserted automatically. Existing files are never overwritten just to create
+a new block.
+
+## Platform and shell support
+
+The platform gate accepts desktop/server Unix-like systems, including macOS,
+Linux, the BSDs, Solaris, and AIX. Local verification is on macOS, including
+sh/bash integration. Other Unix platforms are not independently verified.
+Windows, mobile Python, and browser/WASI runtimes are not supported.
+
+`$SHELL` selects the default **file to edit**:
+
+| Shell | Default file |
+| --- | --- |
+| zsh | `$ZDOTDIR/.zshrc` if set, otherwise `~/.zshrc` |
+| bash | `~/.bashrc` |
+| ksh | `~/.kshrc` |
+| sh, dash, ash | `~/.profile` |
+
+If `$SHELL` is unset or unsupported, envr chooses the first existing file among
+`~/.zshrc`, `~/.bashrc`, and `~/.profile`, falling back to `~/.profile`.
+`--file PATH` overrides this selection. Known filenames select their matching
+validation shell; custom filenames use the supported `$SHELL`, or `sh`.
+The selected shell must be installed to save changes.
+
+These are editing defaults, not a guarantee of what every shell startup mode
+loads. Bash login shells may use `.bash_profile`; ksh may require `ENV` to point
+to `.kshrc`. Use `--file` for your setup. Fish/csh syntax is not supported.
+
+## Commands
+
+| Command | Behavior |
+| --- | --- |
+| `envr` | Open the local editor in your default browser |
+| `envr --file ~/.bash_profile` | Edit a specific file |
+| `envr --no-browser` | Print the URL without opening a browser |
+| `envr --timeout 120` | Stop after 120 seconds; default `0` means until Ctrl-C |
+| `envr --json` | Print one JSON document with platform/config metadata and variable names, **not values**; no prompts/server |
+| `envr -q` | Unix platform gate only; silent, no config file access |
+| `envr --mac -q` | macOS-only gate; silent, no config file access |
+| `envr --version` | Print the version |
+| `python -m envr` | Same command when using the installed interpreter |
+
+Exit codes: `0` = supported platform, `1` = unsupported platform (or server startup
+failure), `2` = invalid usage, `130` = interrupted. Config/marker problems are
+reported but do not change the platform verdict. `--mac` exits `1` off macOS.
+
+## Editing rules and safe saves
+
+- The **first two** marker lines delimit the block. Put them at top level, not
+  inside quoted strings, functions, conditionals, or here-documents.
+- Editable entries are single-line literal `export NAME=value` statements.
+  Plain, single-quoted, double-quoted, and escaped literal values are supported.
+- Names use `[A-Za-z_][A-Za-z0-9_]*` (at most 128 characters); values are at most
+  4096 characters, without newline, NUL, or invalid Unicode. Duplicate names are
+  rejected when adding or editing.
+- Comments and blank lines are preserved. If a block contains shell expressions
+  such as `$HOME`, command substitution, multiline values, or other statements,
+  the **whole block is read-only**. Edit those blocks manually. Nothing is evaluated
+  merely to display the table.
+- Edited values are treated as **literal strings**, safely shell-quoted. Untouched
+  entries, inline comments, line endings, and content outside the block stay intact.
+- Existing symlinks are followed; the target is updated without replacing the link.
+  The target's Unix permission bits are retained. Atomic replacement changes the
+  inode; hard-link relationships, ACLs, and extended attributes are not preserved.
+- External changes are detected before replacement and rejected. Refresh before
+  retrying. Use one editor tab/session per file; this is not a multiuser editor.
+
+On save, envr writes a private temporary candidate in the same directory, runs
+`<shell> -n` against it, and replaces the live file **only if validation succeeds**.
+If validation fails or the shell is unavailable, the original file is unchanged.
+Temporary files are removed afterward.
+
+### Sourcing: important limitation
+
+After saving, envr executes `. <file>` in a **child shell** with a 15-second timeout.
+Raw shell output is discarded so secrets cannot leak into HTTP errors or terminal
+logs; the page reports whether sourcing completed successfully.
+
+**This executes your entire startup file, including commands outside the block.**
+Use envr only with configurations you trust. Syntax validation is not a sandbox.
+Startup guards may skip parts of a file in a noninteractive child shell.
+
+A child process cannot change an already-open terminal's environment. To apply
+changes there, run the appropriate command yourself:
+
+```sh
+source ~/.zshrc     # zsh
+source ~/.bashrc    # bash
+. ~/.profile       # POSIX sh
+```
+
+## Security
+
+The server binds **127.0.0.1 only**, uses an OS-assigned port and a random 192-bit
+token in the URL, and rejects foreign Host/Origin headers. It has no external
+assets, analytics, CORS permissions, or runtime package dependencies. Responses
+use `no-store`, `no-referrer`, `nosniff`, frame denial, and a nonce-based script CSP.
+JSON writes are bounded and validated; displayed values are not inserted as HTML.
+
+The local URL grants **read/write access** and sourcing permission: do not share
+it. It can remain in browser history and terminal scrollback. This is a local
+convenience tool, not encrypted secret storage or a sandbox against other processes
+running as your user. Close the server when finished. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```sh
+git clone https://github.com/Qwik-Tools/envr.git
+cd envr
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e . --group dev
+python -m pytest
+ruff check src tests
+ruff format --check src tests
+mypy src/envr
+python -m build
+python -m twine check dist/*
+```
+
+Tests use temporary config files; they do not edit or source your real startup file.
+Each test has a timeout to prevent accidental indefinite server runs.
+
+```text
+src/envr/system.py       platform detection
+src/envr/shellrc.py      config selection, read/create prompt
+src/envr/secretblock.py  marker extraction helper
+src/envr/secretfile.py   literal parsing, CRUD, validated writes, child sourcing
+src/envr/webview.py      loopback HTTP API and browser table
+src/envr/cli.py          command-line entry point
+```
+
+The distribution is `qwik-envr`; Python imports remain under `envr`. The main
+library interface is `SecretStore.load(path, shell=...)`, then `items()`,
+`add()`, `update()`, `delete()`, `save()`, and `reload()`. `StoreError.code` is
+stable; error details never include values. Store access must be serialized by
+the caller (the HTTP server does this). Maintained by Qwik-Tools / Himakar Reddy.
+
+## License
+
+[MIT](LICENSE).

qwik_envr-0.5.0/README.md

@@ -0,0 +1,192 @@
+# envr
+
+Edit shell environment variables in your browser. Run `envr`, and it opens a local
+table for the `export NAME=value` entries in a marked section of your startup file.
+Add, edit, save, or delete entries without dumping the rest of your shell config.
+
+**Package:** `qwik-envr` on PyPI · **Command:** `envr` · **Python:** 3.9+
+
+## Install
+
+```sh
+pipx install qwik-envr
+# or use a virtual environment
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install qwik-envr
+```
+
+The unrelated PyPI package named `envr` is **not** this project. Do not install both
+in the same environment: they may share the `envr` import/command name.
+
+## Quick start
+
+Put two **identical** marker lines in your shell config:
+
+```sh
+##</env secrets>
+export API_KEY='your-value'
+export DATABASE_URL='postgres://localhost/example'
+##</env secrets>
+```
+
+Then run:
+
+```console
+$ envr
+envr: macOS 26.3 (arm64) -- OK
+envr: 2 exports from ~/.zshrc at http://127.0.0.1:49152/<random-token>/
+envr: Ctrl-C to stop
+```
+
+The port and access token are randomly assigned each run. Your default browser
+opens automatically; the server stays running until **Ctrl-C**. Each row has
+**Save** and **Delete** buttons; use **Add** for new variables. Changes save
+immediately. Refresh the page to reload changes made in another editor.
+
+If the startup file is missing, an interactive run asks before creating an empty,
+owner-only file (`0600`, subject to umask). Add the markers yourself afterward.
+Noninteractive runs never prompt or create a file. Missing markers are reported,
+not inserted automatically. Existing files are never overwritten just to create
+a new block.
+
+## Platform and shell support
+
+The platform gate accepts desktop/server Unix-like systems, including macOS,
+Linux, the BSDs, Solaris, and AIX. Local verification is on macOS, including
+sh/bash integration. Other Unix platforms are not independently verified.
+Windows, mobile Python, and browser/WASI runtimes are not supported.
+
+`$SHELL` selects the default **file to edit**:
+
+| Shell | Default file |
+| --- | --- |
+| zsh | `$ZDOTDIR/.zshrc` if set, otherwise `~/.zshrc` |
+| bash | `~/.bashrc` |
+| ksh | `~/.kshrc` |
+| sh, dash, ash | `~/.profile` |
+
+If `$SHELL` is unset or unsupported, envr chooses the first existing file among
+`~/.zshrc`, `~/.bashrc`, and `~/.profile`, falling back to `~/.profile`.
+`--file PATH` overrides this selection. Known filenames select their matching
+validation shell; custom filenames use the supported `$SHELL`, or `sh`.
+The selected shell must be installed to save changes.
+
+These are editing defaults, not a guarantee of what every shell startup mode
+loads. Bash login shells may use `.bash_profile`; ksh may require `ENV` to point
+to `.kshrc`. Use `--file` for your setup. Fish/csh syntax is not supported.
+
+## Commands
+
+| Command | Behavior |
+| --- | --- |
+| `envr` | Open the local editor in your default browser |
+| `envr --file ~/.bash_profile` | Edit a specific file |
+| `envr --no-browser` | Print the URL without opening a browser |
+| `envr --timeout 120` | Stop after 120 seconds; default `0` means until Ctrl-C |
+| `envr --json` | Print one JSON document with platform/config metadata and variable names, **not values**; no prompts/server |
+| `envr -q` | Unix platform gate only; silent, no config file access |
+| `envr --mac -q` | macOS-only gate; silent, no config file access |
+| `envr --version` | Print the version |
+| `python -m envr` | Same command when using the installed interpreter |
+
+Exit codes: `0` = supported platform, `1` = unsupported platform (or server startup
+failure), `2` = invalid usage, `130` = interrupted. Config/marker problems are
+reported but do not change the platform verdict. `--mac` exits `1` off macOS.
+
+## Editing rules and safe saves
+
+- The **first two** marker lines delimit the block. Put them at top level, not
+  inside quoted strings, functions, conditionals, or here-documents.
+- Editable entries are single-line literal `export NAME=value` statements.
+  Plain, single-quoted, double-quoted, and escaped literal values are supported.
+- Names use `[A-Za-z_][A-Za-z0-9_]*` (at most 128 characters); values are at most
+  4096 characters, without newline, NUL, or invalid Unicode. Duplicate names are
+  rejected when adding or editing.
+- Comments and blank lines are preserved. If a block contains shell expressions
+  such as `$HOME`, command substitution, multiline values, or other statements,
+  the **whole block is read-only**. Edit those blocks manually. Nothing is evaluated
+  merely to display the table.
+- Edited values are treated as **literal strings**, safely shell-quoted. Untouched
+  entries, inline comments, line endings, and content outside the block stay intact.
+- Existing symlinks are followed; the target is updated without replacing the link.
+  The target's Unix permission bits are retained. Atomic replacement changes the
+  inode; hard-link relationships, ACLs, and extended attributes are not preserved.
+- External changes are detected before replacement and rejected. Refresh before
+  retrying. Use one editor tab/session per file; this is not a multiuser editor.
+
+On save, envr writes a private temporary candidate in the same directory, runs
+`<shell> -n` against it, and replaces the live file **only if validation succeeds**.
+If validation fails or the shell is unavailable, the original file is unchanged.
+Temporary files are removed afterward.
+
+### Sourcing: important limitation
+
+After saving, envr executes `. <file>` in a **child shell** with a 15-second timeout.
+Raw shell output is discarded so secrets cannot leak into HTTP errors or terminal
+logs; the page reports whether sourcing completed successfully.
+
+**This executes your entire startup file, including commands outside the block.**
+Use envr only with configurations you trust. Syntax validation is not a sandbox.
+Startup guards may skip parts of a file in a noninteractive child shell.
+
+A child process cannot change an already-open terminal's environment. To apply
+changes there, run the appropriate command yourself:
+
+```sh
+source ~/.zshrc     # zsh
+source ~/.bashrc    # bash
+. ~/.profile       # POSIX sh
+```
+
+## Security
+
+The server binds **127.0.0.1 only**, uses an OS-assigned port and a random 192-bit
+token in the URL, and rejects foreign Host/Origin headers. It has no external
+assets, analytics, CORS permissions, or runtime package dependencies. Responses
+use `no-store`, `no-referrer`, `nosniff`, frame denial, and a nonce-based script CSP.
+JSON writes are bounded and validated; displayed values are not inserted as HTML.
+
+The local URL grants **read/write access** and sourcing permission: do not share
+it. It can remain in browser history and terminal scrollback. This is a local
+convenience tool, not encrypted secret storage or a sandbox against other processes
+running as your user. Close the server when finished. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```sh
+git clone https://github.com/Qwik-Tools/envr.git
+cd envr
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e . --group dev
+python -m pytest
+ruff check src tests
+ruff format --check src tests
+mypy src/envr
+python -m build
+python -m twine check dist/*
+```
+
+Tests use temporary config files; they do not edit or source your real startup file.
+Each test has a timeout to prevent accidental indefinite server runs.
+
+```text
+src/envr/system.py       platform detection
+src/envr/shellrc.py      config selection, read/create prompt
+src/envr/secretblock.py  marker extraction helper
+src/envr/secretfile.py   literal parsing, CRUD, validated writes, child sourcing
+src/envr/webview.py      loopback HTTP API and browser table
+src/envr/cli.py          command-line entry point
+```
+
+The distribution is `qwik-envr`; Python imports remain under `envr`. The main
+library interface is `SecretStore.load(path, shell=...)`, then `items()`,
+`add()`, `update()`, `delete()`, `save()`, and `reload()`. `StoreError.code` is
+stable; error details never include values. Store access must be serialized by
+the caller (the HTTP server does this). Maintained by Qwik-Tools / Himakar Reddy.
+
+## License
+
+[MIT](LICENSE).

qwik_envr-0.5.0/SECURITY.md

@@ -0,0 +1,36 @@
+# Security policy
+
+Report vulnerabilities privately through GitHub's private vulnerability reporting
+for `Qwik-Tools/envr`. If reporting is unavailable, contact a maintainer without
+including real tokens, config files, or tokenized local URLs in a public issue.
+
+## Threat model
+
+Assets are plaintext environment values, the user's startup file, and commands
+executed when that file is sourced. Trust boundaries are the browser-to-loopback
+HTTP connection, JSON edits, and the filesystem/shell boundary.
+
+Foreign websites are denied by a random 192-bit URL capability, Host/Origin
+checks, absence of CORS, JSON-only bounded writes, and CSP/frame restrictions.
+Values are handled as literal strings when edited, not interpolated shell code.
+Syntax checks happen before atomic replacement. Snapshot checks reject external
+changes observed before replacement; this is not a filesystem locking service.
+
+## Residual risks
+
+- Anyone with the complete URL can read/write exports and trigger sourcing.
+- URLs can remain in browser history or terminal scrollback.
+- The HTTP transport is plaintext over IPv4 loopback; do not proxy or expose it.
+- Other programs running as the same user can read config files, inspect process
+  memory, or race filesystem changes. envr does not defend against that actor.
+- Sourcing intentionally executes the entire trusted config with your privileges.
+  The timeout is not a sandbox; spawned processes or existing shell commands can
+  have side effects. Do not open an untrusted configuration with this tool.
+- Unix permission bits are retained, but atomic replacement does not retain ACLs,
+  extended attributes, or hard-link relationships. Use ordinary user-owned UTF-8
+  shell config files, not shared or specially permissioned system files.
+- Use one browser tab and envr process per file. Concurrent browser edits are not
+  a supported collaboration mode.
+
+Only the latest published release is supported. No real secrets should ever be
+included in fixtures, screenshots, bug reports, source archives, or logs.

qwik_envr-0.5.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qwik-envr"
+version = "0.5.0"
+description = "A local browser editor for Unix shell environment variables."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Himakar Reddy" }]
+keywords = ["unix", "shell", "environment", "cli", "secrets"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX",
+  "Operating System :: POSIX :: BSD",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Systems Administration",
+]
+
+[project.urls]
+Homepage = "https://github.com/Qwik-Tools/envr"
+Repository = "https://github.com/Qwik-Tools/envr"
+Issues = "https://github.com/Qwik-Tools/envr/issues"
+
+[project.scripts]
+envr = "envr.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-timeout>=2.3", "ruff>=0.14", "mypy>=1.15,<1.20", "build>=1.2", "twine>=6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envr"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "pyproject.toml", "README.md", "LICENSE", "SECURITY.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+timeout = 15
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.9"
+check_untyped_defs = true

qwik_envr-0.5.0/src/envr/__init__.py

@@ -0,0 +1,62 @@
+"""envr -- a Unix check, plus a browser editor for your shell secrets block.
+
+Public surface:
+
+    is_unix()             -> bool
+    is_mac()              -> bool
+    os_label()            -> str
+    os_version()          -> str
+    platform_info()       -> dict
+    shell_config_path()   -> Path
+    inspect_shell_config()-> ShellReport
+    extract_block()       -> str
+    SecretStore           -- parse/edit/save the export block
+    serve_store()         -> ServeResult
+
+The ``envr`` console script is the only intended entry point; ``python -m envr``
+runs the same command.
+"""
+
+from __future__ import annotations
+
+from .secretblock import SecretsBlockError, extract_block
+from .secretfile import SecretStore, StoreError, quote_value, unquote_value
+from .shellrc import (
+    POSIX_SHELLS,
+    ShellReport,
+    ShellState,
+    config_path_for,
+    detect_shell,
+    inspect_shell_config,
+    shell_config_path,
+    shell_name,
+)
+from .system import is_mac, is_unix, os_label, os_version, platform_info
+from .webview import ServeResult, serve_store
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "POSIX_SHELLS",
+    "SecretStore",
+    "SecretsBlockError",
+    "ServeResult",
+    "ShellReport",
+    "ShellState",
+    "StoreError",
+    "__version__",
+    "config_path_for",
+    "detect_shell",
+    "extract_block",
+    "inspect_shell_config",
+    "is_mac",
+    "is_unix",
+    "os_label",
+    "os_version",
+    "platform_info",
+    "quote_value",
+    "serve_store",
+    "shell_config_path",
+    "shell_name",
+    "unquote_value",
+]

qwik_envr-0.5.0/src/envr/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m envr`` to behave exactly like the ``envr`` script."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())