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

settings/pages/ModulesEdit.tsx

@@ -0,0 +1,74 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import type React from 'react';
+import { useMemo, useState } from 'react';
+import { ModuleForm, type ModuleView } from './components/ModuleForm';
+import { ROUTES } from './routes';
+
+type Props = { modules: ModuleView[] };
+
+function ModulesEdit({ modules }: Props) {
+  const { t } = useT();
+  const [selected, setSelected] = useState(modules[0]?.package);
+  const [q, setQ] = useState('');
+
+  const filtered = useMemo(() => {
+    if (!q) return modules;
+    const query = q.toLowerCase();
+    return modules.filter(
+      (m) =>
+        m.module_name.toLowerCase().includes(query) ||
+        m.package.toLowerCase().includes(query) ||
+        m.fields.some((f) => f.name.toLowerCase().includes(query)),
+    );
+  }, [modules, q]);
+
+  const current = modules.find((m) => m.package === selected);
+
+  return (
+    <div className="flex h-[calc(100vh-64px)]">
+      <aside className="w-64 border-r bg-muted/40 p-3 overflow-y-auto">
+        <input
+          type="text"
+          placeholder={t(keys.settings.modules.search_placeholder)}
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          className="mb-3 w-full rounded border px-2 py-1 text-sm"
+        />
+        <nav className="space-y-1">
+          {filtered.map((m) => (
+            <button
+              key={m.package}
+              type="button"
+              onClick={() => setSelected(m.package)}
+              className={`block w-full rounded px-3 py-2 text-left text-sm ${
+                m.package === selected ? 'bg-primary text-primary-foreground' : 'hover:bg-muted'
+              }`}
+            >
+              <div className="font-medium">{m.module_name}</div>
+              <div className="text-xs opacity-70">
+                {m.fields.length} {t(keys.settings.modules.field_count_suffix)}
+              </div>
+            </button>
+          ))}
+        </nav>
+        <div className="mt-4 border-t pt-3 text-xs">
+          <a href={ROUTES.browse} className="text-primary hover:underline">
+            {t(keys.settings.modules.browse_free_form_link)}
+          </a>
+        </div>
+      </aside>
+
+      <main className="flex-1 overflow-y-auto p-6">
+        {current ? (
+          <ModuleForm module={current} />
+        ) : (
+          <p className="text-muted-foreground">{t(keys.settings.modules.empty_title)}</p>
+        )}
+      </main>
+    </div>
+  );
+}
+
+ModulesEdit.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default ModulesEdit;

settings/pages/components/FieldInput.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react';
+
+export type FieldType = 'bool' | 'int' | 'float' | 'string' | 'json';
+
+export type FieldMeta = {
+  name: string;
+  type: FieldType;
+  value: unknown;
+  default: unknown;
+  description: string;
+  is_secret: boolean;
+  requires_restart: boolean;
+  group: string | null;
+  env_var: string;
+};
+
+type Props = {
+  field: FieldMeta;
+  onChange: (name: string, value: unknown) => void;
+  value: unknown;
+  id?: string;
+};
+
+export function FieldInput({ field, onChange, value, id }: Props) {
+  const [revealed, setRevealed] = useState(false);
+
+  if (field.is_secret && !revealed) {
+    return (
+      <div className="flex items-center gap-2">
+        <input
+          id={id}
+          type="password"
+          value="••••••••"
+          readOnly
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+        <button
+          type="button"
+          className="text-sm text-primary hover:underline"
+          onClick={() => {
+            setRevealed(true);
+            onChange(field.name, ''); // start blank
+          }}
+        >
+          Set new value
+        </button>
+      </div>
+    );
+  }
+
+  switch (field.type) {
+    case 'bool':
+      return (
+        <input
+          id={id}
+          type="checkbox"
+          checked={!!value}
+          onChange={(e) => onChange(field.name, e.target.checked)}
+        />
+      );
+    case 'int':
+    case 'float':
+      return (
+        <input
+          id={id}
+          type="number"
+          step={field.type === 'int' ? '1' : 'any'}
+          value={String(value ?? '')}
+          onChange={(e) =>
+            onChange(field.name, e.target.value === '' ? null : Number(e.target.value))
+          }
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+    case 'json':
+      return (
+        <textarea
+          id={id}
+          rows={3}
+          value={typeof value === 'string' ? value : JSON.stringify(value, null, 2)}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-xs"
+        />
+      );
+    default:
+      return (
+        <input
+          id={id}
+          type="text"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(field.name, e.target.value)}
+          className="w-full rounded border px-2 py-1 font-mono text-sm"
+        />
+      );
+  }
+}

settings/pages/components/ModuleForm.tsx

@@ -0,0 +1,157 @@
+import { router } from '@inertiajs/react';
+import { useEffect, useMemo, useState } from 'react';
+import { FieldInput, type FieldMeta } from './FieldInput';
+
+export type ModuleView = {
+  module_name: string;
+  package: string;
+  env_prefix: string;
+  class_name: string;
+  fields: FieldMeta[];
+};
+
+type Props = { module: ModuleView };
+
+function notEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return false;
+  if (typeof a === 'object' || typeof b === 'object') {
+    return JSON.stringify(a) !== JSON.stringify(b);
+  }
+  return true;
+}
+
+export function ModuleForm({ module: m }: Props) {
+  const initial = useMemo(() => {
+    const o: Record<string, unknown> = {};
+    for (const f of m.fields) o[f.name] = f.value;
+    return o;
+  }, [m.fields]);
+
+  const [values, setValues] = useState<Record<string, unknown>>(initial);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+
+  // Reset the edit buffer whenever the underlying module changes (package
+  // switch, or server-reloaded props after a save/reset).
+  useEffect(() => {
+    setValues(initial);
+    setErrors({});
+  }, [initial]);
+
+  const modifiedFields = useMemo(() => {
+    const s = new Set<string>();
+    for (const name of Object.keys(values)) {
+      if (notEqual(values[name], initial[name])) s.add(name);
+    }
+    return s;
+  }, [values, initial]);
+
+  const defaultByName = useMemo(() => {
+    const o: Record<string, unknown> = {};
+    for (const f of m.fields) o[f.name] = f.default;
+    return o;
+  }, [m.fields]);
+
+  const dirty = modifiedFields.size > 0;
+
+  const grouped = useMemo(() => {
+    const g: Record<string, FieldMeta[]> = {};
+    for (const f of m.fields) {
+      const key = f.group ?? 'General';
+      if (!g[key]) g[key] = [];
+      g[key].push(f);
+    }
+    return g;
+  }, [m.fields]);
+
+  async function onSave() {
+    setBusy(true);
+    setErrors({});
+    const changed: Record<string, unknown> = {};
+    for (const name of modifiedFields) changed[name] = values[name];
+    const resp = await fetch(`/api/settings/modules/${m.package}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(changed),
+    });
+    if (resp.status === 422) {
+      const body = await resp.json();
+      const fieldErrs: Record<string, string> = {};
+      for (const d of body.detail ?? []) {
+        if (d.loc && d.loc.length) fieldErrs[d.loc[d.loc.length - 1]] = d.msg;
+      }
+      setErrors(fieldErrs);
+    } else if (resp.ok) {
+      router.reload({ only: ['modules'] });
+    }
+    setBusy(false);
+  }
+
+  async function onReset(name: string) {
+    await fetch(`/api/settings/modules/${m.package}/${name}`, { method: 'DELETE' });
+    router.reload({ only: ['modules'] });
+  }
+
+  return (
+    <div className="space-y-6">
+      <header className="flex items-center justify-between border-b pb-3">
+        <div>
+          <h2 className="text-xl font-semibold">{m.module_name}</h2>
+          <p className="text-xs font-mono text-muted-foreground">{m.package}</p>
+        </div>
+        <button
+          type="button"
+          disabled={!dirty || busy}
+          onClick={onSave}
+          className="rounded bg-primary px-4 py-2 text-sm text-primary-foreground disabled:opacity-50"
+        >
+          {busy ? 'Saving…' : 'Save'}
+        </button>
+      </header>
+
+      {Object.entries(grouped).map(([group, fields]) => (
+        <section key={group} className="space-y-3">
+          <h3 className="text-sm font-semibold text-muted-foreground">{group}</h3>
+          {fields.map((f) => {
+            const isModified = notEqual(values[f.name], defaultByName[f.name]);
+            return (
+              <div key={f.name} className="grid grid-cols-[1fr_2fr] gap-4 items-start">
+                <div>
+                  <label htmlFor={`field-${m.package}-${f.name}`} className="font-mono text-xs">
+                    {f.name}
+                  </label>
+                  {f.description && (
+                    <p className="mt-1 text-xs text-muted-foreground">{f.description}</p>
+                  )}
+                  {f.requires_restart && isModified && (
+                    <span className="mt-1 inline-block rounded bg-amber-100 px-1.5 py-0.5 text-[10px] uppercase text-amber-900">
+                      Requires restart
+                    </span>
+                  )}
+                </div>
+                <div>
+                  <FieldInput
+                    id={`field-${m.package}-${f.name}`}
+                    field={f}
+                    value={values[f.name]}
+                    onChange={(name, v) => setValues((prev) => ({ ...prev, [name]: v }))}
+                  />
+                  {isModified && (
+                    <button
+                      type="button"
+                      onClick={() => onReset(f.name)}
+                      className="mt-1 text-xs text-primary hover:underline"
+                    >
+                      Reset to default
+                    </button>
+                  )}
+                  {errors[f.name] && <p className="mt-1 text-xs text-red-600">{errors[f.name]}</p>}
+                </div>
+              </div>
+            );
+          })}
+        </section>
+      ))}
+    </div>
+  );
+}

settings/pages/components/ValueInput.tsx

@@ -0,0 +1,92 @@
+import { keys, useT } from '@simple-module-py/i18n';
+
+export type ValueType = 'string' | 'bool' | 'int' | 'float' | 'json';
+
+export const VALUE_TYPES: readonly ValueType[] = [
+  'string',
+  'bool',
+  'int',
+  'float',
+  'json',
+] as const;
+
+type Props = {
+  valueType: ValueType;
+  value: string;
+  onValueChange: (value: string) => void;
+  required?: boolean;
+};
+
+/** Renders the appropriate HTML control for a given `value_type`.
+ *
+ * Controlled component — emits string values regardless of the declared type.
+ * The server re-validates the string against `value_type`.
+ */
+export default function ValueInput({ valueType, value, onValueChange, required = false }: Props) {
+  const { t } = useT();
+
+  if (valueType === 'bool') {
+    const current = value.toLowerCase();
+    return (
+      <select
+        value={current || 'false'}
+        onChange={(e) => onValueChange(e.target.value)}
+        className="border rounded w-full p-2"
+      >
+        <option value="true">true</option>
+        <option value="false">false</option>
+      </select>
+    );
+  }
+
+  if (valueType === 'int') {
+    return (
+      <input
+        type="number"
+        step="1"
+        value={value}
+        onChange={(e) => onValueChange(e.target.value)}
+        required={required}
+        className="border rounded w-full p-2 font-mono"
+      />
+    );
+  }
+
+  if (valueType === 'float') {
+    return (
+      <input
+        type="number"
+        step="any"
+        value={value}
+        onChange={(e) => onValueChange(e.target.value)}
+        required={required}
+        className="border rounded w-full p-2 font-mono"
+      />
+    );
+  }
+
+  if (valueType === 'json') {
+    return (
+      <textarea
+        value={value}
+        onChange={(e) => onValueChange(e.target.value)}
+        required={required}
+        rows={6}
+        placeholder='{"key": "value"}'
+        className="border rounded w-full p-2 font-mono text-sm"
+      />
+    );
+  }
+
+  // string (default)
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => onValueChange(e.target.value)}
+      required={required}
+      placeholder={t(keys.settings.form.value_placeholder)}
+      className="border rounded w-full p-2"
+    />
+  );
+}

settings/pages/routes.ts

@@ -0,0 +1,7 @@
+export const ROUTES = {
+  browse: '/settings',
+  modules: '/settings/modules',
+  create: '/settings/create',
+  edit: (id: number) => `/settings/${id}/edit`,
+  byId: (id: number) => `/settings/${id}`,
+} as const;

settings/registration.py

@@ -0,0 +1,34 @@
+"""Helper modules call from ``register_settings`` to install their BaseSettings.
+
+Two things happen:
+1. A fresh ``BaseSettings`` (pydantic defaults only) is constructed.
+2. The class is recorded in ``app.state.settings.module_registry`` so the
+   hosting lifespan can hydrate it from the DB before module ``on_startup``
+   hooks run.
+
+The module's services dataclass is built from the default settings object and
+attached at ``app.state.<package>``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.constants import MODULE_PACKAGE
+
+
+def register_module_settings(
+    app: FastAPI,
+    package: str,
+    settings_cls: type[BaseSettings],
+    services_factory: Callable[[BaseSettings], Any],
+) -> None:
+    """Register a module's BaseSettings class and mount its services on app.state."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    registry.register(package, settings_cls)
+    defaults = settings_cls()
+    setattr(app.state, package, services_factory(defaults))

settings/reload.py

@@ -0,0 +1,58 @@
+"""Apply field changes to a module's settings, validate, persist, hot-swap."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+from simple_module_core.events import EventBus
+
+from settings.constants import MODULE_PACKAGE
+from settings.contracts.events import SettingsReloaded
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+def _encode(value: Any, value_type: str) -> str:
+    if value_type == "json":
+        return json.dumps(value)
+    return str(value)
+
+
+async def apply_changes_and_reload(
+    app: FastAPI,
+    bus: EventBus,
+    store: SettingsStore,
+    *,
+    package: str,
+    changes: dict[str, Any],
+) -> BaseSettings:
+    """Validate, persist, hot-swap, and publish ``SettingsReloaded``."""
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    cls = registry.get(package)
+    if cls is None:
+        raise KeyError(f"Unknown settings package: {package!r}")
+
+    unknown = set(changes) - set(cls.model_fields)
+    if unknown:
+        raise KeyError(f"Unknown field(s) for {package!r}: {sorted(unknown)}")
+
+    services = getattr(app.state, package)
+    current = services.settings
+    diff = {k: v for k, v in changes.items() if getattr(current, k) != v}
+    if not diff:
+        return current
+
+    merged = current.model_dump()
+    merged.update(diff)
+    validated = cls(**merged)
+
+    for field_name, raw_value in diff.items():
+        vtype = value_type_for_field(cls, field_name)
+        await store.set_override(package, field_name, _encode(raw_value, vtype), vtype)
+
+    services.settings = validated
+    await bus.publish(SettingsReloaded(package=package, changed=tuple(sorted(diff))))
+    return validated

settings/service.py

@@ -0,0 +1,162 @@
+"""Setting service implementation — scoped key/value CRUD + resolution."""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from settings.constants import SYSTEM_SCOPE_ID, VALUE_TYPE_STRING
+from settings.contracts.schemas import (
+    SettingCreate,
+    SettingOut,
+    SettingScope,
+    SettingUpdate,
+    SettingUpsert,
+)
+from settings.models import Setting
+
+
+class SettingService:
+    """Async CRUD + scope resolution for key/value settings.
+
+    Resolution precedence when calling ``resolve`` / ``get_resolved_value``:
+    USER > TENANT > SYSTEM. The first match in that chain is returned.
+    """
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    # ── Listing ─────────────────────────────────────────────────────
+
+    async def list_all(self) -> list[SettingOut]:
+        result = await self.db.execute(
+            select(Setting).order_by(Setting.scope, Setting.scope_id, Setting.key)
+        )
+        return [SettingOut.model_validate(row) for row in result.scalars()]
+
+    async def list_by_scope(
+        self, scope: SettingScope, scope_id: str = SYSTEM_SCOPE_ID
+    ) -> list[SettingOut]:
+        stmt = (
+            select(Setting)
+            .where(Setting.scope == scope.value, Setting.scope_id == scope_id)
+            .order_by(Setting.key)
+        )
+        result = await self.db.execute(stmt)
+        return [SettingOut.model_validate(row) for row in result.scalars()]
+
+    # ── Lookup ──────────────────────────────────────────────────────
+
+    async def get_by_id(self, setting_id: int) -> SettingOut | None:
+        entity = await self.db.get(Setting, setting_id)
+        if entity is None:
+            return None
+        return SettingOut.model_validate(entity)
+
+    async def get_scoped(self, scope: SettingScope, scope_id: str, key: str) -> SettingOut | None:
+        entity = await self._find(scope, scope_id, key)
+        return SettingOut.model_validate(entity) if entity is not None else None
+
+    async def resolve(
+        self,
+        key: str,
+        user_id: str | None = None,
+        tenant_id: str | None = None,
+    ) -> SettingOut | None:
+        if user_id:
+            entity = await self._find(SettingScope.USER, user_id, key)
+            if entity is not None:
+                return SettingOut.model_validate(entity)
+        if tenant_id:
+            entity = await self._find(SettingScope.TENANT, tenant_id, key)
+            if entity is not None:
+                return SettingOut.model_validate(entity)
+        entity = await self._find(SettingScope.SYSTEM, SYSTEM_SCOPE_ID, key)
+        return SettingOut.model_validate(entity) if entity is not None else None
+
+    async def get_resolved_value(
+        self,
+        key: str,
+        user_id: str | None = None,
+        tenant_id: str | None = None,
+        default: str | None = None,
+    ) -> str | None:
+        found = await self.resolve(key, user_id=user_id, tenant_id=tenant_id)
+        return found.value if found is not None else default
+
+    # ── Mutations ───────────────────────────────────────────────────
+
+    async def create(self, data: SettingCreate) -> SettingOut:
+        entity = Setting(**data.model_dump())
+        self.db.add(entity)
+        await self.db.flush()
+        await self.db.refresh(entity)
+        return SettingOut.model_validate(entity)
+
+    async def update(self, setting_id: int, data: SettingUpdate) -> SettingOut | None:
+        entity = await self.db.get(Setting, setting_id)
+        if entity is None:
+            return None
+        for field, value in data.model_dump(exclude_unset=True).items():
+            setattr(entity, field, value)
+        await self.db.flush()
+        await self.db.refresh(entity)
+        return SettingOut.model_validate(entity)
+
+    async def upsert_scoped(
+        self,
+        scope: SettingScope,
+        scope_id: str,
+        key: str,
+        data: SettingUpsert,
+    ) -> SettingOut:
+        entity = await self._find(scope, scope_id, key)
+        if entity is None:
+            entity = Setting(
+                scope=scope.value,
+                scope_id=scope_id,
+                key=key,
+                value=data.value,
+                value_type=(
+                    data.value_type.value if data.value_type is not None else VALUE_TYPE_STRING
+                ),
+                description=data.description,
+            )
+            self.db.add(entity)
+        else:
+            entity.value = data.value
+            if data.value_type is not None:
+                entity.value_type = data.value_type.value
+            # Honor explicit description=None as "clear"; skip only when unset.
+            if "description" in data.model_fields_set:
+                entity.description = data.description
+        await self.db.flush()
+        await self.db.refresh(entity)
+        return SettingOut.model_validate(entity)
+
+    async def delete(self, setting_id: int) -> bool:
+        entity = await self.db.get(Setting, setting_id)
+        if entity is None:
+            return False
+        await self.db.delete(entity)
+        await self.db.flush()
+        return True
+
+    async def delete_scoped(self, scope: SettingScope, scope_id: str, key: str) -> bool:
+        entity = await self._find(scope, scope_id, key)
+        if entity is None:
+            return False
+        await self.db.delete(entity)
+        await self.db.flush()
+        return True
+
+    # ── Internals ───────────────────────────────────────────────────
+
+    async def _find(self, scope: SettingScope, scope_id: str, key: str) -> Setting | None:
+        stmt = select(Setting).where(
+            Setting.scope == scope.value,
+            Setting.scope_id == scope_id,
+            Setting.key == key,
+        )
+        result = await self.db.execute(stmt)
+        return result.scalar_one_or_none()