@chill-sharp/ui-core 1.1.12

package/.agents/skills/chillsharp-current-user-preferences/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: chillsharp-current-user-preferences
+description: Configure, expose, and consume ChillSharp.Auth's cached current-user culture, time zone, date-format, number-format, and theme preferences in server logic and UI clients.
+---
+
+# ChillSharp Current User Preferences
+
+Use this skill when a ChillSharp feature needs the authenticated user's display culture, time zone, date format, or number format. It covers server-side lifecycle hooks and UI/client consumption of the authoritative `AuthUser` preferences. Do not use it for browser-only preferences unrelated to `AuthUser`.
+
+## Model
+
+`ChillUserPreferences` is an immutable snapshot with `DisplayCultureName`, `DisplayTimeZone`, `DisplayDateFormat`, `DisplayNumberFormat`, and `PreferredTheme`. The backend stores `PreferredTheme` as an opaque string. In UI Core, unauthenticated users follow browser `prefers-color-scheme`; clients register extra themes with `provideChillSharpUiCore({ additionalThemes: ['theme-name'] })`. Entity hooks read the snapshot synchronously through:
+
+```csharp
+var preferences = context.GetCurrentUserPreferences();
+```
+
+Never load `AuthUser` from an `OnCreate`, `OnUpdate`, or other lifecycle hook merely to obtain these values.
+
+## Auth integration
+
+`AddChillAuthApi` registers `IChillAuthUserPreferencesAccessor` and the singleton `IChillAuthUserPreferencesCache`. Login and token refresh warm the snapshot; `ChillAuthService` refreshes it after an `AuthUser` save and removes it for deleted or renamed external identities.
+
+For a custom host DbContext, inject the scoped accessor and implement the two `IChillContext` methods below. Keep the accessor optional only when the context must also be constructible outside DI, such as for migrations or tests.
+
+```csharp
+private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+public ChillUserPreferences GetCurrentUserPreferences() =>
+    _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+public string GetDefaultUserCultureName()
+{
+    var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+    return string.IsNullOrWhiteSpace(cultureName) ? GetPrimaryCultureName() : cultureName;
+}
+```
+
+The accessor is cache-only: when there is no authenticated principal or no warmed snapshot, it returns `ChillUserPreferences.Empty`. Do not add a fallback database query to lifecycle hooks.
+
+## API and client use
+
+The authenticated endpoint `GET /api/chill-auth/current-user-preferences` returns the same `ChillUserPreferences` snapshot as JSON:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2"
+}
+```
+
+Use this endpoint after authentication and when restoring a session; do not infer the active display culture or time zone from the browser, operating system, token claims, or auth-management user endpoints. The C#, Python, TypeScript, Angular, Vue, and React clients expose it as `GetCurrentUserPreferences`, `get_current_user_preferences`, or `getCurrentUserPreferences`; the Vue and React packages also provide `useCurrentUserPreferences`.
+
+In Angular UI Core, inject `ChillService` and read its `userPreferences` signal (or its `displayCultureName`, `displayTimeZone`, `displayDateFormat`, and `displayNumberFormat` projections). Use these values to select UI language, format and parse dates and numbers, and convert UTC timestamps. Treat all fields as optional and choose an explicit fallback only when needed.
+
+## Entity use
+
+Use `DisplayTimeZone` as an IANA zone identifier only after validating it with the application's time-zone policy. Treat all fields as optional and provide an explicit fallback where one is required.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var timeZone = context.GetCurrentUserPreferences().DisplayTimeZone;
+    // Apply application-specific behavior only when timeZone is available.
+}
+```
+
+For full setup and cache behavior, read [CurrentUserPreferences.md](../../../doc/CurrentUserPreferences.md).

package/.agents/skills/chillsharp-ui-template/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: chillsharp-ui-template
+description: Build and customize Angular ChillSharp client projects from the UI template, including plugins, overrides, i18n, permissions, and runtime configuration.
+---
+
+# ChillSharp UI Client Template
+
+Use this skill for work in `chill-sharp-ui-template` or a client repository created from it.
+
+The template owns runtime configuration, branding, routes, client plugins, and overrides. Shared controls, data access, schema rendering, auth, i18n primitives, and permission evaluation belong in `@chill-sharp/ui-core` and the ChillSharp client packages. Do not copy or patch shared package internals.
+
+Keep `provideClientTemplateProviders()` in the app provider chain. Register feature routes in `src/app/core/plugins/register-client-plugins.ts`; register deliberate provider replacements in `src/app/core/overrides/register-client-overrides.ts`. Use public package APIs only.
+
+Treat backend schema as the source of entity/property metadata rather than duplicating it in Angular. Use runtime API configuration from `public/env.js`. Request localized text with an explicit culture and preserve backend fallback behavior. UI permission checks can hide or disable operations, but the protected backend is the enforcement boundary.
+
+Permission-sensitive features must account for `Module -> Entity -> Property`: entity `Query/Create/Update/Delete` is separate from property `See/Modify`. Never infer write access from a visible field.
+
+Add plugins under the client-owned plugin folder, register providers through the override/provider points, keep tenant/feature flags/branding in runtime config, add focused tests, and run `npm run build` after registration changes. This `.agents/skills` directory travels with the template into client repositories.

package/README.md

@@ -0,0 +1,103 @@
+# @chill-sharp/ui-core
+
+Private Angular package that contains the shared ChillSharp UI implementation extracted from the standard `chill-sharp-ng-ui` application.
+
+## Scope
+
+This package contains:
+
+- shared layouts
+- shared pages
+- shared services
+- workspace/task infrastructure
+- reusable ChillSharp form and table components
+- shared models and runtime helpers
+- base theme styles
+
+This package intentionally does not contain a client-specific shell application.
+
+Client shells and client-owned plugins should live outside this package.
+
+## Install
+
+```bash
+npm install @chill-sharp/ui-core
+```
+
+## Build And Release
+
+See [`HOW_TO_BUILD.md`](/c:/source/personal/chill-sharp/chill-sharp/extra/chill-sharp-ui-core/HOW_TO_BUILD.md) for the workflow to rebuild, version, and publish the library after a change.
+
+## Plugin Documentation
+
+`@chill-sharp/ui-core` currently supports client extension through template-owned routes, provider override placeholders, and runtime-loaded remote workspace tasks. It does not yet expose a single formal plugin registration API.
+
+See [`../HOW_TO_CREATE_UI_CORE_PLUGIN_README.md`](../HOW_TO_CREATE_UI_CORE_PLUGIN_README.md) before documenting a client plugin or remote workspace task package.
+
+## Theme import
+
+Import the shared theme from your client shell:
+
+```scss
+@import '@chill-sharp/ui-core/styles/core-theme.scss';
+```
+
+## Package entry points
+
+- `ChillSharpUiRootComponent`: router host component for the shell
+- `CHILL_SHARP_UI_ROUTES`: default route tree for the standard ChillSharp UI
+- `provideChillSharpUiCore()`: shared providers and initializers
+
+## Status
+
+This is the initial extraction of the current Angular implementation into a reusable `ui-core` package. Client shells should consume it and own only bootstrap, configuration, branding, theme overrides, and local plugins.
+
+## Service worker cache
+
+`@chill-sharp/ui-core` ships `service-worker/chill-sharp-service-worker.js`.
+The template and GDF load it from their client-owned `public/sw.js`; future package
+upgrades update the shared behavior without replacing client options.
+
+For an existing client, integrate once:
+
+1. Upgrade `@chill-sharp/ui-core` to a package containing the worker (1.1.6 or later).
+2. Add this entry to the Angular build assets (and test assets if applicable):
+   `{"glob":"*.js","input":"node_modules/@chill-sharp/ui-core/service-worker","output":"/"}`.
+3. Create/adapt `public/sw.js`:
+
+   ```js
+   self.CHILL_SHARP_SW_OPTIONS = {
+     cachePrefix: 'my-app',
+     cacheVersion: 'v2',
+     cacheTimeoutMs: 10 * 60 * 1000,
+     appShell: ['/', '/index.html'],
+     legacyCacheNames: []
+   };
+   importScripts('./chill-sharp-service-worker.js');
+   ```
+
+4. Register `/sw.js` with `{ updateViaCache: 'none' }` on page load. Serve both
+   worker scripts with `Cache-Control: no-cache, must-revalidate`, not immutable.
+   HTTPS (or localhost) is required. Apps hosted below `/` must adjust shell URLs,
+   registration URL and scope for their base path.
+
+Do not register a second worker alongside an existing custom worker for the same
+scope; integrate the shared worker into the client wrapper. Cache names belonging
+to `cachePrefix` with old versions are removed on activation. Use `legacyCacheNames`
+for explicitly named old caches with a different prefix. Unrelated caches survive.
+
+Schema, schema-list and entity-options GETs expire at ten minutes, including
+cross-origin API requests. Expired entries fetch from the network without using
+the browser HTTP cache; expired metadata is not returned as an offline fallback.
+Bearer responses vary by Authorization. Other APIs and runtime configuration are
+network-only. Static runtime assets use the same lifetime; the precached app shell
+remains available as a navigation fallback when offline.
+
+Every `get-schema?update=true` request reaches the server. It clears all cached
+schemas, lists and entity options before and after the request, as do `set-schema`
+and `set-entity-options`. Reads during a write wait for it to finish, and old
+in-flight reads cannot refill the cache after invalidation. The first ordinary GET
+after the update or a page reload fetches a fresh schema and starts a new lifetime.
+
+Run `npm run test:service-worker` in `extra/chill-sharp-ui-core` for the regression
+tests covering expiration, invalidation, authorization and request races.

package/chill-sharp-ui-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chill-sharp-ui-core.d.ts","sourceRoot":"","sources":["../src/chill-sharp-ui-core.ts"],"names":[],"mappings":"AAAA;;GAEG;;AAEH,cAAc,cAAc,CAAC"}

package/doc/AIAssistedDevelopment/README.md

@@ -0,0 +1,185 @@
+# AI-Assisted Development Guide
+
+Versione italiana: [Italiano](../it/AIAssistedDevelopment/README.md)
+
+
+This document explains how ChillSharp can help when you build software with AI assistance and still want the codebase to remain structured, stable, and reviewable.
+
+The key idea is simple: AI tools are much more reliable when they work inside a constrained, repetitive, well-defined architecture than when they are asked to manually keep many controllers, DTOs, endpoints, and validation paths in sync.
+
+ChillSharp does not make AI-generated code automatically correct. What it does is reduce the amount of surface area that AI has to generate and maintain.
+
+## Why This Matters
+
+A common failure mode in AI-assisted backend development is that the model touches too many moving parts at once:
+
+- controllers
+- DTO mappings
+- request/response contracts
+- validation logic
+- authorization checks
+- duplicated CRUD behaviors
+
+The more files and custom endpoints you have, the easier it is for AI to introduce accidental interface drift, inconsistent behavior, or broad refactors that were never intended.
+
+ChillSharp reduces that risk by moving a large part of the backend surface into a uniform model-driven runtime.
+
+## How ChillSharp Helps
+
+### 1. Business logic grows inside a structured environment
+
+With ChillSharp, the main extension points are explicit and predictable:
+
+- `ChillEntity`
+- `ChillQuery`
+- `OnValidation()`
+- lifecycle hooks such as `OnCreate()`, `OnUpdate()`, `OnAfterUpdate()`, `OnDelete()`, and `OnSelect()`
+- metadata through `[ChillProperty]` and related annotations
+
+That gives AI a narrower and more structured place to make changes.
+
+Instead of asking an AI model to invent yet another controller, request DTO, response DTO, mapper, validator, and route contract, you can often ask it to:
+
+- add a property
+- add validation
+- add a query filter
+- add lifecycle logic
+- adjust permission rules
+
+This usually produces smaller and safer edits.
+
+### 2. Lower risk of accidental endpoint refactoring
+
+ChillSharp exposes a standard API surface through `app.MapChillApi()`, with stable operations such as:
+
+- `POST /api/chill/query`
+- `POST /api/chill/lookup`
+- `POST /api/chill/find`
+- `POST /api/chill/create`
+- `POST /api/chill/update`
+- `POST /api/chill/delete`
+
+Because the transport surface is centralized, adding or evolving business entities does not require AI to keep rewriting a growing set of per-entity controllers and route definitions.
+
+This reduces a specific AI risk:
+
+- changing endpoint names by accident
+- changing payload shapes inconsistently
+- implementing one endpoint differently from the rest
+- breaking clients through unnecessary API refactors
+
+The interface still evolves when your model evolves, but the CRUD and query mechanics do not have to be re-authored every time.
+
+### 3. Endpoints grow in a uniform way
+
+In a traditional hand-written backend, every new entity tends to create more duplicated API code. Over time, small differences accumulate:
+
+- one controller validates differently
+- another controller returns slightly different payloads
+- another endpoint forgets an authorization check
+- another DTO mapper omits a field
+
+AI tools amplify this problem because they continue the local pattern they see, even when the local pattern is already inconsistent.
+
+ChillSharp pushes the system in the opposite direction: entities and queries plug into the same runtime model, so growth is more uniform by default.
+
+That uniformity helps both:
+
+- human maintainers reviewing AI-produced changes
+- AI tools reasoning over the codebase with less ambiguity
+
+### 4. Smaller program payload for AI tools
+
+When a project relies on many custom CRUD controllers, DTO classes, mapping layers, and repetitive endpoint definitions, AI needs more repository context to make a safe change.
+
+That increases:
+
+- token usage
+- latency
+- cost
+- the chance that the model misses one of the duplicated layers
+
+ChillSharp reduces this burden because much of the repetitive transport logic is already handled by the framework runtime.
+
+In practice this means an AI task can often be solved by reading and changing:
+
+- one entity
+- one query
+- one validation rule
+- one permission definition
+
+instead of a long chain of related files.
+
+### 5. Lower pressure for continuous large-scale refactoring
+
+Without a model-driven framework, teams often ask AI to keep refactoring a growing list of:
+
+- endpoints
+- controllers
+- DTOs
+- validators
+- mappers
+- permission checks
+
+That is expensive and fragile. It also encourages broad automated rewrites that may not deliver business value.
+
+ChillSharp reduces the need for that style of maintenance because the generic CRUD/query surface is already centralized.
+
+That has practical benefits:
+
+- lower AI token consumption
+- fewer broad refactors across repetitive files
+- less review effort for generated code
+- lower compute usage for the same feature work
+
+If you care about both engineering efficiency and energy efficiency, this is one of the strongest arguments for using a uniform runtime instead of a large amount of repeated endpoint boilerplate.
+
+## What ChillSharp Is Good At In AI Workflows
+
+ChillSharp is a good fit when you want AI to help with:
+
+- extending domain entities
+- adding validation rules
+- adding query capabilities
+- exposing model changes through an existing generic API surface
+- keeping permissions and metadata closer to the model
+
+This is usually a better fit than asking AI to repeatedly generate large sets of CRUD infrastructure code.
+
+## What ChillSharp Does Not Solve
+
+ChillSharp does not remove the need for engineering review. In particular, you still need to verify:
+
+- business rules are correct
+- authorization rules are correct
+- exposed properties are intentional
+- model changes do not break consumers
+- AI-generated lifecycle logic is actually safe
+
+ChillSharp reduces duplication and drift. It does not remove the need for judgment.
+
+## Recommended Positioning
+
+If you want a short and defensible way to describe this in documentation or architecture notes, use something like:
+
+"ChillSharp helps AI-assisted development by centralizing repetitive API mechanics into a model-driven runtime. This reduces accidental interface drift, keeps endpoint behavior more uniform, and lowers the amount of code and repository context that AI tools must generate and maintain."
+
+## Practical Checklist
+
+If you want to use ChillSharp as an AI-friendly backend architecture, the baseline is:
+
+1. keep business entities and queries as the main place where feature behavior is defined
+2. use `[ChillProperty]` consistently so the DTO and validation surface remains intentional
+3. prefer `OnValidation()` and lifecycle hooks over ad-hoc controller logic
+4. avoid reintroducing repetitive custom CRUD endpoints unless there is a real need
+5. review model changes carefully because a model-driven surface can affect multiple client operations at once
+6. keep permissions and authentication aligned with the same model-driven approach
+
+## Related Documents
+
+- [../README.md](../README.md)
+- [../RegisterContext.md](../RegisterContext.md)
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)

package/doc/AttachmentModel/README.md

@@ -0,0 +1,173 @@
+# Attachment Module
+
+Versione italiana: [Italiano](../it/AttachmentModel/README.md)
+
+
+`ChillSharp.Attachment` adds a built-in attachment entity plus upload and download endpoints backed by a filesystem archive.
+
+## What It Adds
+
+- `Attachment` Chill entity persisted in the `attachment` table
+- generic Chill CRUD support for attachment metadata
+- `GET /api/chill-attachment/attachment/download?guid=...`
+- `POST /api/chill-attachment/attachment/upload`
+
+Because `Attachment` is a real `ChillEntity`, it is also exposed through schema discovery and can be managed through the standard Chill CRUD endpoints once the host `DbContext` implements `IChillAttachmentDbContext`.
+
+The module also exposes an `AttachmentQuery` Chill query type, which client helpers can use to list attachments linked to a target entity.
+
+## Register The Module
+
+Add the module model to your context and expose the `DbSet`:
+
+```csharp
+using ChillSharp.Attachment;
+using ChillSharp.Attachment.Model;
+
+public class AppDbContext : DbContext, IChillContext, IChillAttachmentDbContext
+{
+    public DbSet<Attachment> Attachments => Set<Attachment>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.AddChillAttachmentModel();
+    }
+
+    public string GetChillTypePrefix() => "MyApp.Data";
+}
+```
+
+When the context implements `IChillAttachmentDbContext`, `services.AddChillApi<AppDbContext>()` automatically registers the attachment endpoints.
+
+## Archive Root Configuration
+
+The module reads the archive root from:
+
+- startup options via `services.Configure<ChillAttachmentOptions>(...)`
+- environment variable `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT`
+
+Example:
+
+```csharp
+builder.Services.Configure<ChillAttachmentOptions>(options =>
+{
+    options.ArchiveRoot = "/srv/chill/attachments";
+});
+```
+
+Or through environment:
+
+```env
+CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/srv/chill/attachments
+```
+
+## Archive Layout
+
+Files are stored under the configured archive root using:
+
+```csharp
+public static string BuildAttachmentPath(
+    string archiveRoot,
+    string attachToChillType,
+    Guid id,
+    string extension,
+    DateTime createdAtUtc)
+```
+
+The resulting layout is:
+
+```text
+{archiveRoot}/{attachToChillType}/{year}/{guid[0..2]}/{guid[2..4]}/{guid}{extension}
+```
+
+Example:
+
+```text
+/srv/chill/attachments/Post/2026/ab/cd/abcd1234....pdf
+```
+
+## Upload Endpoint
+
+`POST /api/chill-attachment/attachment/upload`
+
+Multipart form fields:
+
+- `attachToChillType`
+- `attachToGuid`
+- `title`
+- `description`
+- `public`
+- one or more `file` parts
+
+For each uploaded file the module:
+
+1. creates an `Attachment` Chill entity through `ChillEngine`
+2. stores the physical file in the archive
+3. returns the created attachment DTO payload
+
+## Download Endpoint
+
+`GET /api/chill-attachment/attachment/download?guid={attachmentGuid}`
+
+Behavior:
+
+- loads the `Attachment` entity from the database
+- resolves the archived file path
+- returns the file using the stored original filename and mime type
+- allows anonymous download when `Public == true`
+- requires an authenticated user when `Public == false`
+
+## Client Helpers
+
+### `.NET`
+
+`ChillSharp.Client` now includes attachment helpers:
+
+```csharp
+var post = new ChillDtoEntity
+{
+    Guid = postGuid,
+    ChillType = "Model.Post"
+};
+
+var uploaded = await client.UploadAttachmentAsync(
+    post,
+    File.ReadAllBytes("contract.pdf"),
+    "contract.pdf",
+    "application/pdf",
+    title: "Signed contract",
+    description: "Customer-facing version",
+    isPublic: false);
+
+var attachments = await client.GetAttachmentsAsync(post);
+var fileBytes = await client.DownloadAttachmentAsync(uploaded[0]);
+```
+
+Available overloads cover:
+
+- upload from file path
+- upload from `byte[]`
+- upload from `Stream`
+- download by attachment `Guid`
+- download by attachment `ChillDtoEntity`
+
+### TypeScript / Angular / React / Vue / Python
+
+The generic client libraries under `extra-libs/` expose matching helpers:
+
+- TypeScript: `uploadAttachment()`, `uploadAttachments()`, `getAttachments()`, `downloadAttachment()`
+- Angular: same helpers through `ChillSharpNgClient` as `Observable` wrappers
+- React and Vue: same helpers through the raw client returned by `useChillSharpClient()`
+- Python: `upload_attachment()`, `upload_attachments()`, `get_attachments()`, `download_attachment()`
+
+## Generic CRUD
+
+Attachment metadata remains available through the standard Chill endpoints:
+
+- `POST /api/chill/create`
+- `POST /api/chill/find`
+- `POST /api/chill/update`
+- `POST /api/chill/delete`
+
+Deleting an attachment through ChillSharp also removes the archived file from disk.