simple-module-settings 0.0.1__py3-none-any.whl

settings/env_vars.py

@@ -0,0 +1,18 @@
+"""Map package names to their historical ``SM_*`` env-var prefix.
+
+Used by ``_module_settings`` to label fields in the admin UI and by the
+``sm-settings import-from-env`` CLI to locate legacy env values. Most
+packages follow ``SM_<PACKAGE_UPPER>_``; the exceptions are listed below.
+"""
+
+from __future__ import annotations
+
+_PACKAGE_ENV_PREFIX: dict[str, str] = {
+    "background_tasks": "SM_BG_TASKS_",
+    "file_storage": "SM_FILE_STORAGE_",
+    "host": "SM_",
+}
+
+
+def env_prefix_for(package: str) -> str:
+    return _PACKAGE_ENV_PREFIX.get(package, f"SM_{package.upper()}_")

settings/hydrate.py

@@ -0,0 +1,63 @@
+"""Resolve a module's BaseSettings from DB overrides + pydantic defaults.
+
+A field's declared Python type maps to one of the five ``value_type`` labels
+understood by SettingsStore (``string | bool | int | float | json``). The
+hydrator reads overrides, parses each according to its stored ``value_type``,
+and constructs the BaseSettings — pydantic enforces field validators and any
+``@model_validator`` hooks.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import get_origin
+
+from pydantic_settings import BaseSettings
+
+from settings.store import SettingsStore
+
+
+def value_type_for_field(cls: type[BaseSettings], field_name: str) -> str:
+    """Return the ``value_type`` label for a field based on its annotation.
+
+    - ``bool`` → ``"bool"``
+    - ``int`` → ``"int"``
+    - ``float`` → ``"float"``
+    - ``str`` and enums → ``"string"``
+    - ``list``, ``dict``, and other container types → ``"json"``
+    """
+    info = cls.model_fields[field_name]
+    ann = info.annotation
+    origin = get_origin(ann)
+    if origin is not None:
+        return "json"
+    if ann is bool:
+        return "bool"
+    if ann is int:
+        return "int"
+    if ann is float:
+        return "float"
+    return "string"
+
+
+def _parse(raw: str, value_type: str):
+    if value_type == "bool":
+        return raw.lower() in ("1", "true", "yes", "on")
+    if value_type == "int":
+        return int(raw)
+    if value_type == "float":
+        return float(raw)
+    if value_type == "json":
+        return json.loads(raw)
+    return raw
+
+
+async def hydrate_settings[T: BaseSettings](cls: type[T], store: SettingsStore, package: str) -> T:
+    """Construct ``cls`` with DB overrides merged over pydantic defaults."""
+    raw_overrides = await store.get_overrides(package)
+    parsed: dict[str, object] = {}
+    for field_name, (raw, vtype) in raw_overrides.items():
+        if field_name not in cls.model_fields:
+            continue
+        parsed[field_name] = _parse(raw, vtype)
+    return cls(**parsed)

settings/locales/en.json

@@ -0,0 +1,71 @@
+{
+  "browse": {
+    "title": "Settings",
+    "new_button": "New Setting",
+    "empty_title": "No settings yet",
+    "empty_description": "Get started by creating your first setting.",
+    "edit_link": "Edit",
+    "delete_link": "Delete",
+    "delete_confirm": "Delete setting \"{key}\"? This cannot be undone."
+  },
+  "table": {
+    "scope": "Scope",
+    "scope_id": "Scope ID",
+    "key": "Key",
+    "value": "Value",
+    "value_type": "Type",
+    "description": "Description",
+    "actions": "Actions"
+  },
+  "scopes": {
+    "system": "System",
+    "tenant": "Tenant",
+    "user": "User"
+  },
+  "value_types": {
+    "string": "String",
+    "bool": "Boolean",
+    "int": "Integer",
+    "float": "Float",
+    "json": "JSON"
+  },
+  "form": {
+    "scope_label": "Scope",
+    "scope_id_label": "Scope ID",
+    "scope_id_placeholder": "Tenant or user id (empty for system)",
+    "key_label": "Key",
+    "key_placeholder": "e.g. feature.enabled",
+    "value_type_label": "Type",
+    "value_label": "Value",
+    "value_placeholder": "Enter a value",
+    "description_label": "Description",
+    "description_placeholder": "Optional description"
+  },
+  "create": {
+    "title": "New Setting",
+    "submit_button": "Create"
+  },
+  "edit": {
+    "title": "Edit Setting",
+    "submit_button": "Save"
+  },
+  "modules": {
+    "title": "Module Settings",
+    "description": "Read-only view of every module's runtime configuration, autodiscovered from the app. Secrets are masked.",
+    "back_link": "Back to overrides",
+    "empty_title": "No modules with settings",
+    "no_fields": "No fields declared.",
+    "secret_badge": "secret",
+    "browse_link": "View module settings",
+    "search_placeholder": "Search modules or fields…",
+    "field_count_suffix": "fields",
+    "browse_free_form_link": "View free-form settings",
+    "table": {
+      "field": "Field",
+      "env_var": "Env var",
+      "value": "Value",
+      "default": "Default",
+      "description": "Description"
+    }
+  }
+}

settings/models.py

@@ -0,0 +1,50 @@
+"""SQLModel tables for the Settings module."""
+
+from __future__ import annotations
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from settings.constants import (
+    DESCRIPTION_MAX_LENGTH,
+    KEY_MAX_LENGTH,
+    MODULE_PACKAGE,
+    SCOPE_ID_MAX_LENGTH,
+    SCOPE_MAX_LENGTH,
+    SCOPE_SYSTEM,
+    SYSTEM_SCOPE_ID,
+    TABLE_SETTING,
+    UQ_SCOPE_KEY,
+    VALUE_MAX_LENGTH,
+    VALUE_TYPE_MAX_LENGTH,
+    VALUE_TYPE_STRING,
+)
+
+Base = create_module_base(MODULE_PACKAGE)
+
+
+class Setting(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """A typed key/value configuration entry scoped to system, tenant, or user.
+
+    Resolution precedence when a consumer asks for a key: USER > TENANT >
+    SYSTEM. Uniqueness is enforced across the (scope, scope_id, key) tuple
+    so the same key can live at different scopes without collision.
+
+    ``value`` is always stored as a string. ``value_type`` advertises how
+    the bytes should be interpreted ("string", "bool", "int", "float",
+    "json") so UIs pick the right input control and pydantic can reject
+    inputs that don't parse.
+    """
+
+    __tablename__ = TABLE_SETTING
+    __table_args__ = (UniqueConstraint("scope", "scope_id", "key", name=UQ_SCOPE_KEY),)
+
+    id: int | None = Field(default=None, primary_key=True)
+    scope: str = Field(default=SCOPE_SYSTEM, max_length=SCOPE_MAX_LENGTH, index=True)
+    scope_id: str = Field(default=SYSTEM_SCOPE_ID, max_length=SCOPE_ID_MAX_LENGTH, index=True)
+    key: str = Field(max_length=KEY_MAX_LENGTH, index=True)
+    value: str = Field(max_length=VALUE_MAX_LENGTH)
+    value_type: str = Field(default=VALUE_TYPE_STRING, max_length=VALUE_TYPE_MAX_LENGTH)
+    description: str | None = Field(default=None, max_length=DESCRIPTION_MAX_LENGTH)

settings/module.py

@@ -0,0 +1,76 @@
+"""Settings module definition."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from settings.constants import (
+    ALL_PERMISSIONS,
+    API_PREFIX,
+    LOCALE_NAMESPACE,
+    MENU_ICON,
+    MENU_LABEL,
+    MENU_ORDER,
+    MENU_URL,
+    MODULE_NAME,
+    MODULE_PACKAGE,
+    PERM_GROUP,
+    VIEW_PREFIX,
+)
+
+
+class SettingsModule(ModuleBase):
+    meta = ModuleMeta(
+        name=MODULE_NAME,
+        route_prefix=API_PREFIX,
+        view_prefix=VIEW_PREFIX,
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from settings.contracts.registry import SettingsRegistry
+        from settings.module_registry import ModuleSettingsRegistry
+        from settings.services import SettingsServices
+        from settings.settings import SettingsSettings
+
+        services = SettingsServices(
+            settings=SettingsSettings(),
+            registry=SettingsRegistry(),
+            module_registry=ModuleSettingsRegistry(),
+        )
+        setattr(app.state, MODULE_PACKAGE, services)
+
+        # Self-register so the UI lists our own settings alongside other modules.
+        services.module_registry.register("settings", SettingsSettings)
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from settings.endpoints.api import router as api
+        from settings.endpoints.module_api import router as module_api
+        from settings.endpoints.views import router as views
+
+        api_router.include_router(module_api)
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=MENU_LABEL,
+                url=MENU_URL,
+                icon=MENU_ICON,
+                order=MENU_ORDER,
+                section=MenuSection.SIDEBAR,
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(PERM_GROUP, list(ALL_PERMISSIONS))
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {LOCALE_NAMESPACE: base}

settings/module_registry.py

@@ -0,0 +1,33 @@
+"""Registry of per-module pydantic BaseSettings classes.
+
+Populated during each module's ``register_settings`` via
+``register_module_settings``. The hosting lifespan reads this at startup
+to hydrate every module's effective settings from the DB.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic_settings import BaseSettings
+
+
+@dataclass(slots=True)
+class ModuleSettingsRegistry:
+    """In-memory map of ``package`` → ``BaseSettings`` subclass."""
+
+    _classes: dict[str, type[BaseSettings]] = field(default_factory=dict)
+
+    def register(self, package: str, cls: type[BaseSettings]) -> None:
+        if package in self._classes:
+            raise ValueError(f"{package!r} already registered")
+        self._classes[package] = cls
+
+    def get(self, package: str) -> type[BaseSettings] | None:
+        return self._classes.get(package)
+
+    def all_packages(self) -> list[str]:
+        return sorted(self._classes)
+
+    def items(self) -> list[tuple[str, type[BaseSettings]]]:
+        return sorted(self._classes.items())

settings/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/settings",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Settings module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

settings/pages/Browse.tsx

@@ -0,0 +1,103 @@
+import { router } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import type React from 'react';
+import type { ValueType } from './components/ValueInput';
+import { ROUTES } from './routes';
+
+type Scope = 'system' | 'tenant' | 'user';
+
+type Setting = {
+  id: number;
+  scope: Scope;
+  scope_id: string;
+  key: string;
+  value: string;
+  value_type: ValueType;
+  description: string | null;
+};
+
+type Props = { settings: Setting[] };
+
+function Browse({ settings }: Props) {
+  const { t } = useT();
+
+  function handleDelete(setting: Setting) {
+    if (!window.confirm(t(keys.settings.browse.delete_confirm, { key: setting.key }))) return;
+    router.delete(ROUTES.byId(setting.id));
+  }
+
+  return (
+    <div className="p-6">
+      <div className="flex items-center justify-between mb-4">
+        <h1 className="text-2xl font-semibold">{t(keys.settings.browse.title)}</h1>
+        <div className="flex items-center gap-3">
+          <a href={ROUTES.modules} className="text-sm text-primary hover:underline">
+            {t(keys.settings.modules.browse_link)}
+          </a>
+          <a
+            href={ROUTES.create}
+            className="rounded bg-primary px-3 py-1.5 text-primary-foreground"
+          >
+            {t(keys.settings.browse.new_button)}
+          </a>
+        </div>
+      </div>
+      {settings.length === 0 ? (
+        <div className="py-12 text-center">
+          <h2 className="text-lg font-medium">{t(keys.settings.browse.empty_title)}</h2>
+          <p className="text-sm text-muted-foreground mt-1">
+            {t(keys.settings.browse.empty_description)}
+          </p>
+        </div>
+      ) : (
+        <table className="w-full text-left border-collapse">
+          <thead>
+            <tr className="border-b">
+              <th className="py-2 pr-4">{t(keys.settings.table.scope)}</th>
+              <th className="py-2 pr-4">{t(keys.settings.table.scope_id)}</th>
+              <th className="py-2 pr-4">{t(keys.settings.table.key)}</th>
+              <th className="py-2 pr-4">{t(keys.settings.table.value_type)}</th>
+              <th className="py-2 pr-4">{t(keys.settings.table.value)}</th>
+              <th className="py-2 pr-4">{t(keys.settings.table.description)}</th>
+              <th className="py-2">{t(keys.settings.table.actions)}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {settings.map((setting) => (
+              <tr key={setting.id} className="border-b">
+                <td className="py-2 pr-4">{t(keys.settings.scopes[setting.scope])}</td>
+                <td className="py-2 pr-4 font-mono text-sm text-muted-foreground">
+                  {setting.scope_id || '—'}
+                </td>
+                <td className="py-2 pr-4 font-mono text-sm">{setting.key}</td>
+                <td className="py-2 pr-4 text-xs uppercase text-muted-foreground">
+                  {t(keys.settings.value_types[setting.value_type])}
+                </td>
+                <td className="py-2 pr-4 font-mono text-sm">{setting.value}</td>
+                <td className="py-2 pr-4 text-muted-foreground">{setting.description ?? ''}</td>
+                <td className="py-2">
+                  <div className="flex gap-3">
+                    <a href={ROUTES.edit(setting.id)} className="text-primary hover:underline">
+                      {t(keys.settings.browse.edit_link)}
+                    </a>
+                    <button
+                      type="button"
+                      onClick={() => handleDelete(setting)}
+                      className="text-destructive hover:underline"
+                    >
+                      {t(keys.settings.browse.delete_link)}
+                    </button>
+                  </div>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}
+
+Browse.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Browse;

settings/pages/Create.tsx

@@ -0,0 +1,113 @@
+import { useForm } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import type React from 'react';
+import ValueInput, { VALUE_TYPES, type ValueType } from './components/ValueInput';
+import { ROUTES } from './routes';
+
+const SCOPES = ['system', 'tenant', 'user'] as const;
+type Scope = (typeof SCOPES)[number];
+
+function Create() {
+  const { t } = useT();
+  const { data, setData, post, processing, errors } = useForm({
+    scope: 'system' as Scope,
+    scope_id: '',
+    key: '',
+    value_type: 'string' as ValueType,
+    value: '',
+    description: '',
+  });
+
+  function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    post(ROUTES.browse);
+  }
+
+  return (
+    <div className="p-6 max-w-xl">
+      <h1 className="text-2xl font-semibold mb-4">{t(keys.settings.create.title)}</h1>
+      <form onSubmit={handleSubmit} className="space-y-3">
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.scope_label)}</span>
+          <select
+            value={data.scope}
+            onChange={(e) => setData('scope', e.target.value as Scope)}
+            className="border rounded w-full p-2"
+          >
+            {SCOPES.map((s) => (
+              <option key={s} value={s}>
+                {t(keys.settings.scopes[s])}
+              </option>
+            ))}
+          </select>
+          {errors.scope && <p className="text-sm text-destructive">{errors.scope}</p>}
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.scope_id_label)}</span>
+          <input
+            value={data.scope_id}
+            onChange={(e) => setData('scope_id', e.target.value)}
+            placeholder={t(keys.settings.form.scope_id_placeholder)}
+            className="border rounded w-full p-2 font-mono"
+          />
+          {errors.scope_id && <p className="text-sm text-destructive">{errors.scope_id}</p>}
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.key_label)}</span>
+          <input
+            value={data.key}
+            onChange={(e) => setData('key', e.target.value)}
+            required
+            placeholder={t(keys.settings.form.key_placeholder)}
+            className="border rounded w-full p-2 font-mono"
+          />
+          {errors.key && <p className="text-sm text-destructive">{errors.key}</p>}
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.value_type_label)}</span>
+          <select
+            value={data.value_type}
+            onChange={(e) => setData('value_type', e.target.value as ValueType)}
+            className="border rounded w-full p-2"
+          >
+            {VALUE_TYPES.map((vt) => (
+              <option key={vt} value={vt}>
+                {t(keys.settings.value_types[vt])}
+              </option>
+            ))}
+          </select>
+        </label>
+        <div className="block">
+          <span className="block text-sm">{t(keys.settings.form.value_label)}</span>
+          <ValueInput
+            valueType={data.value_type}
+            value={data.value}
+            onValueChange={(v) => setData('value', v)}
+            required
+          />
+          {errors.value && <p className="text-sm text-destructive">{errors.value}</p>}
+        </div>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.description_label)}</span>
+          <textarea
+            value={data.description}
+            onChange={(e) => setData('description', e.target.value)}
+            placeholder={t(keys.settings.form.description_placeholder)}
+            className="border rounded w-full p-2"
+          />
+        </label>
+        <button
+          type="submit"
+          disabled={processing}
+          className="rounded bg-primary px-3 py-1.5 text-primary-foreground disabled:opacity-50"
+        >
+          {t(keys.settings.create.submit_button)}
+        </button>
+      </form>
+    </div>
+  );
+}
+
+Create.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Create;

settings/pages/Edit.tsx

@@ -0,0 +1,102 @@
+import { useForm } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import type React from 'react';
+import ValueInput, { type ValueType } from './components/ValueInput';
+import { ROUTES } from './routes';
+
+type Scope = 'system' | 'tenant' | 'user';
+
+type Setting = {
+  id: number;
+  scope: Scope;
+  scope_id: string;
+  key: string;
+  value: string;
+  value_type: ValueType;
+  description: string | null;
+};
+
+type Props = { setting: Setting };
+
+function Edit({ setting }: Props) {
+  const { t } = useT();
+  const { data, setData, put, processing, errors } = useForm({
+    value: setting.value,
+    value_type: setting.value_type,
+    description: setting.description ?? '',
+  });
+
+  function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    put(ROUTES.byId(setting.id));
+  }
+
+  return (
+    <div className="p-6 max-w-xl">
+      <h1 className="text-2xl font-semibold mb-4">{t(keys.settings.edit.title)}</h1>
+      <form onSubmit={handleSubmit} className="space-y-3">
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.scope_label)}</span>
+          <input
+            value={t(keys.settings.scopes[setting.scope])}
+            disabled
+            className="border rounded w-full p-2 bg-muted"
+          />
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.scope_id_label)}</span>
+          <input
+            value={setting.scope_id}
+            disabled
+            className="border rounded w-full p-2 font-mono bg-muted"
+          />
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.key_label)}</span>
+          <input
+            defaultValue={setting.key}
+            disabled
+            className="border rounded w-full p-2 font-mono bg-muted"
+          />
+        </label>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.value_type_label)}</span>
+          <input
+            value={t(keys.settings.value_types[setting.value_type])}
+            disabled
+            className="border rounded w-full p-2 bg-muted"
+          />
+        </label>
+        <div className="block">
+          <span className="block text-sm">{t(keys.settings.form.value_label)}</span>
+          <ValueInput
+            valueType={data.value_type}
+            value={data.value}
+            onValueChange={(v) => setData('value', v)}
+            required
+          />
+          {errors.value && <p className="text-sm text-destructive">{errors.value}</p>}
+        </div>
+        <label className="block">
+          <span className="block text-sm">{t(keys.settings.form.description_label)}</span>
+          <textarea
+            value={data.description}
+            onChange={(e) => setData('description', e.target.value)}
+            className="border rounded w-full p-2"
+          />
+        </label>
+        <button
+          type="submit"
+          disabled={processing}
+          className="rounded bg-primary px-3 py-1.5 text-primary-foreground disabled:opacity-50"
+        >
+          {t(keys.settings.edit.submit_button)}
+        </button>
+      </form>
+    </div>
+  );
+}
+
+Edit.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Edit;