dotfill 0.1.0__tar.gz

dotfill-0.1.0/LICENSE

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

dotfill-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: dotfill
+Version: 0.1.0
+Summary: Local-only helper to populate and maintain a personal .env file with API tokens and identity variables
+Keywords: api-tokens,dotenv,env,local-first,secrets
+Author: Osama Masoud
+Author-email: Osama Masoud <osama.masoud@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Dist: typer>=0.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.8
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.10.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/omasoud/dotfill
+Project-URL: Repository, https://github.com/omasoud/dotfill
+Project-URL: Documentation, https://github.com/omasoud/dotfill/tree/main/docs
+Project-URL: Issues, https://github.com/omasoud/dotfill/issues
+Description-Content-Type: text/markdown
+
+# dotfill
+
+dotfill is a local-only helper for maintaining token and identity variables in a personal `.env` file. It runs a Python CLI plus a localhost web UI, reads TOML configuration, and writes only after explicit user action.
+
+Generic `dotfill` ships with no services, identities, domains, token names, or import aliases. A user config or a wrapper package supplies those definitions.
+
+## Installation
+
+For CLI use, install dotfill as an isolated tool:
+
+```powershell
+uv tool install dotfill
+```
+
+or:
+
+```powershell
+pipx install dotfill
+```
+
+For use as a library or project dependency:
+
+```powershell
+uv add dotfill
+```
+
+or:
+
+```powershell
+pip install dotfill
+```
+
+dotfill requires Python 3.14 or newer.
+
+## Quick Start
+
+```powershell
+dotfill status
+dotfill
+dotfill config path
+dotfill config open
+```
+
+Useful options:
+
+```powershell
+dotfill --config-root C:\tmp\dotfill-config --profile demo status
+dotfill --env-path C:\work\project\.env
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) walks through the first config and dashboard run.
+- [TOML config schema](docs/config-schema.md) is the full user-facing config reference.
+- [Troubleshooting](docs/troubleshooting.md) covers common setup, config, import, and service-test issues.
+
+Maintainer requirements, design notes, and implementation tracking live under `dev/docs/`.
+
+## Configuration
+
+dotfill loads two optional TOML files from the resolved config directory:
+
+```text
+config_common.toml
+config.toml
+```
+
+`config_common.toml` is intended for managed baseline configuration. `config.toml` is intended for user-owned overrides. Both files must include `version = 1` when present.
+
+See [docs/config-schema.md](docs/config-schema.md) for the complete schema.
+
+Default config root:
+
+```text
+platformdirs.user_config_dir("dotfill", appauthor=False, roaming=True)
+```
+
+Profiles live under `profiles/<name>` inside the config root.
+
+Example:
+
+```toml
+version = 1
+name = "Example profile"
+
+[target]
+default_env_path = "~/.env"
+
+[identities.WORK_EMAIL]
+source = "literal"
+value = "alice@example.com"
+
+[identities.WORK_USER]
+source = "local_part"
+from = "WORK_EMAIL"
+
+[derived.WORK_USERNAME]
+from_identity = "WORK_EMAIL"
+
+[services.EXAMPLE]
+display_name = "Example"
+token_var = "EXAMPLE_TOKEN"
+token_url = "https://service.example.com/users/{WORK_USER}/tokens"
+test_url = "https://service.example.com/me"
+auth = "bearer"
+tls_verify = true
+icon = "key"
+
+[import_aliases.OLD_EXAMPLE_TOKEN]
+target = "EXAMPLE_TOKEN"
+```
+
+Set `enabled = false` in `config.toml` to disable an inherited service, identity, derived variable, or import alias.
+
+## `.env` Behavior
+
+The target `.env` contains ordinary environment values only. dotfill no longer reads legacy service or derived-variable meta-configuration from `.env`; those assignments are unrelated content unless their exact names are explicitly configured as managed variables in TOML.
+
+The parser/writer preserves comments, blank lines, unrelated variables, unrelated duplicates, and line endings. Duplicate managed variables are rejected before writes.
+
+## Local UI
+
+`dotfill` starts a server bound to `127.0.0.1`, opens the dashboard, and serves static assets from the installed package. The dashboard can:
+
+- show configured identities, derived variables, services, config directory, and target `.env`;
+- save service tokens;
+- fill missing enabled derived variables during saves;
+- import token/derived values from another `.env`-like file;
+- test configured bearer tokens on explicit user action.
+
+When no services are configured, the dashboard shows an empty generic state.
+
+## Privacy
+
+- No cloud backend, accounts, telemetry, or remote sync.
+- Raw token values are not returned by state/import APIs.
+- Dropped import values are kept only in backend session memory as secret values.
+- The browser keeps session and token input in memory only; no browser storage is used.
+- Service tests send `Authorization: Bearer <token>` only to configured test URLs.
+- Service tests verify TLS by default. Use `tls_verify = false` only when a configured service explicitly requires it.
+
+## Wrapper Packages
+
+Wrapper packages can provide managed `config_common.toml` content and launch dotfill through:
+
+```python
+from dotfill.entrypoints import run_dotfill
+
+raise SystemExit(
+    run_dotfill(
+        default_profile="team",
+        before_config_load=sync_managed_config,
+    )
+)
+```
+
+Wrappers should not import the Typer app directly. User overrides remain in `config.toml`.
+
+## Development
+
+From a source checkout:
+
+```powershell
+uv sync
+uv run pytest
+uv run dotfill status
+uv build
+```
+
+If the virtual environment is activated, `dotfill --help` works directly. Without activation, use `uv run dotfill ...` or `.\.venv\Scripts\dotfill.exe ...`.

dotfill-0.1.0/README.md

@@ -0,0 +1,170 @@
+# dotfill
+
+dotfill is a local-only helper for maintaining token and identity variables in a personal `.env` file. It runs a Python CLI plus a localhost web UI, reads TOML configuration, and writes only after explicit user action.
+
+Generic `dotfill` ships with no services, identities, domains, token names, or import aliases. A user config or a wrapper package supplies those definitions.
+
+## Installation
+
+For CLI use, install dotfill as an isolated tool:
+
+```powershell
+uv tool install dotfill
+```
+
+or:
+
+```powershell
+pipx install dotfill
+```
+
+For use as a library or project dependency:
+
+```powershell
+uv add dotfill
+```
+
+or:
+
+```powershell
+pip install dotfill
+```
+
+dotfill requires Python 3.14 or newer.
+
+## Quick Start
+
+```powershell
+dotfill status
+dotfill
+dotfill config path
+dotfill config open
+```
+
+Useful options:
+
+```powershell
+dotfill --config-root C:\tmp\dotfill-config --profile demo status
+dotfill --env-path C:\work\project\.env
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) walks through the first config and dashboard run.
+- [TOML config schema](docs/config-schema.md) is the full user-facing config reference.
+- [Troubleshooting](docs/troubleshooting.md) covers common setup, config, import, and service-test issues.
+
+Maintainer requirements, design notes, and implementation tracking live under `dev/docs/`.
+
+## Configuration
+
+dotfill loads two optional TOML files from the resolved config directory:
+
+```text
+config_common.toml
+config.toml
+```
+
+`config_common.toml` is intended for managed baseline configuration. `config.toml` is intended for user-owned overrides. Both files must include `version = 1` when present.
+
+See [docs/config-schema.md](docs/config-schema.md) for the complete schema.
+
+Default config root:
+
+```text
+platformdirs.user_config_dir("dotfill", appauthor=False, roaming=True)
+```
+
+Profiles live under `profiles/<name>` inside the config root.
+
+Example:
+
+```toml
+version = 1
+name = "Example profile"
+
+[target]
+default_env_path = "~/.env"
+
+[identities.WORK_EMAIL]
+source = "literal"
+value = "alice@example.com"
+
+[identities.WORK_USER]
+source = "local_part"
+from = "WORK_EMAIL"
+
+[derived.WORK_USERNAME]
+from_identity = "WORK_EMAIL"
+
+[services.EXAMPLE]
+display_name = "Example"
+token_var = "EXAMPLE_TOKEN"
+token_url = "https://service.example.com/users/{WORK_USER}/tokens"
+test_url = "https://service.example.com/me"
+auth = "bearer"
+tls_verify = true
+icon = "key"
+
+[import_aliases.OLD_EXAMPLE_TOKEN]
+target = "EXAMPLE_TOKEN"
+```
+
+Set `enabled = false` in `config.toml` to disable an inherited service, identity, derived variable, or import alias.
+
+## `.env` Behavior
+
+The target `.env` contains ordinary environment values only. dotfill no longer reads legacy service or derived-variable meta-configuration from `.env`; those assignments are unrelated content unless their exact names are explicitly configured as managed variables in TOML.
+
+The parser/writer preserves comments, blank lines, unrelated variables, unrelated duplicates, and line endings. Duplicate managed variables are rejected before writes.
+
+## Local UI
+
+`dotfill` starts a server bound to `127.0.0.1`, opens the dashboard, and serves static assets from the installed package. The dashboard can:
+
+- show configured identities, derived variables, services, config directory, and target `.env`;
+- save service tokens;
+- fill missing enabled derived variables during saves;
+- import token/derived values from another `.env`-like file;
+- test configured bearer tokens on explicit user action.
+
+When no services are configured, the dashboard shows an empty generic state.
+
+## Privacy
+
+- No cloud backend, accounts, telemetry, or remote sync.
+- Raw token values are not returned by state/import APIs.
+- Dropped import values are kept only in backend session memory as secret values.
+- The browser keeps session and token input in memory only; no browser storage is used.
+- Service tests send `Authorization: Bearer <token>` only to configured test URLs.
+- Service tests verify TLS by default. Use `tls_verify = false` only when a configured service explicitly requires it.
+
+## Wrapper Packages
+
+Wrapper packages can provide managed `config_common.toml` content and launch dotfill through:
+
+```python
+from dotfill.entrypoints import run_dotfill
+
+raise SystemExit(
+    run_dotfill(
+        default_profile="team",
+        before_config_load=sync_managed_config,
+    )
+)
+```
+
+Wrappers should not import the Typer app directly. User overrides remain in `config.toml`.
+
+## Development
+
+From a source checkout:
+
+```powershell
+uv sync
+uv run pytest
+uv run dotfill status
+uv build
+```
+
+If the virtual environment is activated, `dotfill --help` works directly. Without activation, use `uv run dotfill ...` or `.\.venv\Scripts\dotfill.exe ...`.

dotfill-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "dotfill"
+version = "0.1.0"
+description = "Local-only helper to populate and maintain a personal .env file with API tokens and identity variables"
+readme = "README.md"
+authors = [
+    { name = "Osama Masoud", email = "osama.masoud@gmail.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = ["api-tokens", "dotenv", "env", "local-first", "secrets"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.8",
+    "python-dotenv>=1.0",
+    "httpx>=0.27",
+    "platformdirs>=4.10.0",
+]
+
+[project.scripts]
+dotfill = "dotfill.entrypoints:main"
+
+[project.urls]
+Homepage = "https://github.com/omasoud/dotfill"
+Repository = "https://github.com/omasoud/dotfill"
+Documentation = "https://github.com/omasoud/dotfill/tree/main/docs"
+Issues = "https://github.com/omasoud/dotfill/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-mock>=3.14",
+    "respx>=0.21",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+
+[tool.uv]
+exclude-newer = "2 days" # Exclude packages released in the last 2 days as a protection against undiscovered supply chain vulnerabilities.

dotfill-0.1.0/src/dotfill/__init__.py

@@ -0,0 +1,8 @@
+"""dotfill — local-only API token/identity .env helper."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dotfill")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

dotfill-0.1.0/src/dotfill/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m dotfill`."""
+
+from .entrypoints import main
+
+if __name__ == "__main__":
+    main()