@salsita-ai/sdk 0.50.0-develop.a926ccd94f → 0.50.0-develop.a9ee99dc86

package/dist/domain/application/application-config.d.ts

@@ -6,42 +6,33 @@ import type { Logger } from '@salsita-ai/common/utils';
 import type { SessionRole, SessionTokenPayload } from '@salsita-ai/contracts/api';
 import type { CellValue } from '@salsita-ai/contracts/webhook';
 import type { AdminIntegrationService } from '#package/react-sdk';
-import type { DomainComponentOptic } from '../components/domain-component-optic.js';
-import type { $DomainEntity, DomainEntity, DomainFactory, ProductPreset, SystemComponentTypeConstraint } from '../core/index.js';
-import type { AnalyticsSystem, DomainContextSystems, TransformerFactory, Transformers } from '../domain-context/index.js';
-import type { RegistrableTransformer } from '../domain-context/transformers/index.js';
-import type { ElementRegistration } from './element-registration.js';
-import type { HandlerRegistration } from './handler-registration.js';
+import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
+import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
+import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
+import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
-export type ImportedTransformer<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> = {
+type TransformerExport = ReturnType<TransformerFactory<any, any, any, any, any, any, any>> | RegistrableTransformer<any, any, any, any, any, any, any>;
+/** The transformers one `src/transformers/` file exports, under the name of the file. */
+export type ImportedTransformer = {
     name: string;
-    transformer: ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES> | ReadonlyArray<ReturnType<TransformerFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>> | RegistrableTransformer<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>>;
+    transformer: TransformerExport | ReadonlyArray<TransformerExport>;
 };
 export type SpecTransformer = {
     name: string;
     priority?: number;
 };
-export interface DataSchemaPrimitiveField {
-    readonly type: 'string' | 'number' | 'integer' | 'boolean';
-    readonly enum?: ReadonlyArray<string | number>;
-    readonly description?: string;
-}
-export interface DataSchemaLocalizedField {
-    readonly type: 'localized';
-    readonly description?: string;
-}
-export interface DataSchemaArrayField {
-    readonly type: 'array';
-    readonly items: 'string' | 'number' | 'boolean';
-    readonly description?: string;
+/**
+ * The transformers of an application: the `src/transformers/` files as project modules, and the spec's
+ * `transformers` section, which selects them by name and orders them by priority. A plain-function
+ * export is selected by its file name; a transformer made with `build(name)` by that name, which the spec
+ * parser requires to match the file name with case and dashes ignored. The runtime spec resolves the two
+ * into the factory the store system calls on every update.
+ */
+export interface TransformersConfig {
+    readonly importedTransformers: readonly ProjectModule[];
+    readonly specTransformers: readonly SpecTransformer[];
 }
-export type DataSchemaFieldObject = DataSchemaPrimitiveField | DataSchemaLocalizedField | DataSchemaArrayField;
-export type DataSchemaField = 'string' | 'number' | 'boolean' | readonly ['string', 'null'] | readonly ['number', 'null'] | readonly ['boolean', 'null'] | DataSchemaFieldObject;
-export type DataSchema = Record<string, DataSchemaField>;
-export type DataCellValue = CellValue | null | {
-    readonly $lang: Record<string, string>;
-} | readonly CellValue[];
 export type DataSpecEntry = {
     readonly definition: DataSchema;
     readonly chunk?: string;
@@ -64,67 +55,6 @@ export type DataSpec = {
 export type ChunksSpec = Readonly<Record<string, {
     readonly scope: string;
 }>>;
-/**
- * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
- * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
- * string in the current locale.
- */
-export interface AssistantFieldSource {
-    readonly source: string;
-    readonly localized?: true;
-}
-/**
- * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
- * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
- * name the agent addresses the group by, `instanceName` the component instance it reads,
- * `description` the manifest's text replacing the component's group description, and `dryRuns`
- * whether the recipes of the group can be dry-run.
- */
-export interface AssistantRecipeGroup {
-    readonly groupId: string;
-    readonly instanceName: string;
-    readonly description?: string;
-    readonly dryRuns: boolean;
-}
-/**
- * The options edge of one writable field the assistant manifest links to its component. `field` is
- * the delta field of `modify<Type>` the choices are for, `edgeName` the field of `<Type>Meta` that
- * lists them, `componentType` and `instanceName` the component instance they are read from, and
- * `validate` whether `modify<Type>` rejects a value that is not among them, and `dryRuns` whether
- * the choices can be dry-run.
- */
-export interface AssistantFieldOptions {
-    readonly field: string;
-    readonly edgeName: string;
-    readonly componentType: 'materialSwatch' | 'attributeSelection' | 'distanceDimensionSelect';
-    readonly instanceName: string;
-    readonly validate: boolean;
-    readonly dryRuns: boolean;
-}
-/**
- * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
- * the GraphQL schema text prepared at parse time; `fields` maps each GraphQL object type's exposed
- * fields (type name → GraphQL field name) to the stored field or expression its resolvers read;
- * `deletableTypes` lists the entity types the `deleteEntity` mutation may delete, with aliases
- * already expanded, and absent means none; `writableFields` maps, per entity type with a
- * `modify<Type>` mutation, each field of its delta input to the stored property it writes, and
- * absent means no entity type is writable; `childRecipes` lists, per entity type with a `meta` field,
- * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
- * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
- * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
- * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
- * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
- */
-export interface AssistantManifest {
-    readonly sdl: string;
-    readonly fields: Readonly<Record<string, Readonly<Record<string, AssistantFieldSource>>>>;
-    readonly deletableTypes?: readonly string[];
-    readonly writableFields?: Readonly<Record<string, Readonly<Record<string, string>>>>;
-    readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
-    readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
-    readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
-    readonly actions?: Readonly<Record<string, string>>;
-}
 export type AdminPagesSpec = {
     readonly presets?: boolean | {
         readonly categoryNavigationState?: string;
@@ -171,9 +101,11 @@ export interface DomainConfig<ENTITIES extends DomainEntity<string>, ALLOWED_ROO
      */
     readonly domainFactory: DomainFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
     /**
-     * Components attached to the domain used for the Application to work.
+     * Components attached to the domain used for the Application to work, as project modules: the
+     * `src/components/` files and the optics a generated file lists. The runtime spec validates and
+     * flattens them.
      */
-    readonly componentOptics: ReadonlyArray<DomainComponentOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, SystemComponentTypeConstraint>>;
+    readonly componentOptics: readonly ProjectModule[];
     /**
      * List of languages that the user will be able to provide in multi-lingual text fields in the Admin UI
      */
@@ -352,15 +284,16 @@ export interface ApplicationConfig<ENTITIES extends DomainEntity<string>, ALLOWE
     readonly chunks?: ChunksSpec;
     readonly dataSpec?: DataSpec;
     readonly publishedDataHash?: string;
-    readonly assistant?: AssistantManifest | null;
-    /**
-     * Factory for transformers that will be registered in the store system and called on any update.
-     */
-    readonly createTransformers?: (ctx: DomainContextSystems<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>) => Transformers<ENTITIES>;
+    readonly assistant?: AssistantResolvedManifest | null;
+    /** The project's transformers; the runtime spec validates the files and builds the store's transformer factory from them. */
+    readonly transformers?: TransformersConfig;
     readonly adminNavigation?: AdminNavigationConfig<ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES> | undefined;
     readonly adminDomain: DomainConfig<ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
-    readonly handlers: ReadonlyArray<HandlerRegistration<any, any>>;
-    readonly elements: readonly ElementRegistration[];
+    /** The `src/handlers/` and `src/elements/` files as project modules; the runtime spec validates and flattens both. */
+    readonly handlers: readonly ProjectModule[];
+    readonly elements: readonly ProjectModule[];
+    /** The SDK's default element registrations; a project element with the same name replaces one. */
+    readonly defaultElements?: readonly ElementRegistration[];
     readonly mount: MountConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>;
 }
 export {};

package/dist/domain/application/assistant/assistant-fields.d.ts

@@ -0,0 +1,12 @@
+import type { AssistantDeclaredField, AssistantResolvedField } from './assistant-resolved-manifest.js';
+/** Combines the effective description with allowed string values. */
+export declare const describeAssistantValues: (description: string | undefined, values: readonly string[] | undefined) => string | undefined;
+/** Applies GraphQL field inheritance identically at parse time and after session narrowing. */
+export declare const mergeAssistantFields: (inherited: ReadonlyArray<readonly AssistantDeclaredField[]>, own: readonly AssistantDeclaredField[], ownEnumValues: (source: string) => readonly string[] | undefined, conflict: (name: string, first: string, second: string) => void) => readonly AssistantDeclaredField[];
+/**
+ * The serializable form of a merged field of one alias or type. Merging keeps the inherited entry of
+ * a field declared twice, so the lens tags are taken from `own`, the declarations of that alias or
+ * type itself: each lens condition then comes from its own declaration, at parse time and after
+ * session narrowing alike.
+ */
+export declare const resolveAssistantField: (field: AssistantDeclaredField, own: readonly AssistantDeclaredField[]) => AssistantResolvedField;

package/dist/domain/application/assistant/assistant-fields.js

@@ -0,0 +1 @@
+export const describeAssistantValues=(e,s)=>{if(!s?.length)return e;let t=`One of: ${s.map(e=>`"${e}"`).join(", ")}.`;return e?`${e}${/[.!?]$/.test(e)?"":"."} ${t}`:t};export const mergeAssistantFields=(e,s,t,n)=>{let r=new Map,i=new Set(s);for(let t of[...e.flat(),...s]){let e=r.get(t.name);e?e.source!==t.source?n(t.name,e.source,t.source):r.set(t.name,{...e,...i.has(t)&&t.describedByManifest?{description:t.description,describedByManifest:!0,valueDescription:t.valueDescription}:{}}):r.set(t.name,t)}return[...r.values()].map(e=>{let s=e.enumValues&&t(e.source);return s?{...e,enumValues:s,description:describeAssistantValues(e.valueDescription,s)}:e})};export const resolveAssistantField=(e,s)=>{let t=s.find(s=>s.name===e.name&&s.source===e.source)?.lenses;return{name:e.name,source:e.source,localized:e.localized,type:e.type,...void 0===e.description?{}:{description:e.description},...t?.length?{lenses:t}:{}}};

package/dist/domain/application/assistant/assistant-manifest.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
+ * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
+ * string in the current locale.
+ */
+export interface AssistantFieldSource {
+    readonly source: string;
+    readonly localized?: true;
+}
+/**
+ * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
+ * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
+ * name the agent addresses the group by, `instanceName` the component instance it reads,
+ * `description` the manifest's text replacing the component's group description, and `dryRuns`
+ * whether the recipes of the group can be dry-run.
+ */
+export interface AssistantRecipeGroup {
+    readonly groupId: string;
+    readonly instanceName: string;
+    readonly description?: string;
+    readonly dryRuns: boolean;
+}
+/**
+ * The options edge of one writable field the assistant manifest links to its component. `field` is
+ * the delta field of `modify<Type>` the choices are for, `edgeName` the field of `<Type>Meta` that
+ * lists them, `componentType` and `instanceName` the component instance they are read from, and
+ * `validate` whether `modify<Type>` rejects a value that is not among them, and `dryRuns` whether
+ * the choices can be dry-run.
+ */
+export interface AssistantFieldOptions {
+    readonly field: string;
+    readonly edgeName: string;
+    readonly componentType: 'materialSwatch' | 'attributeSelection' | 'distanceDimensionSelect';
+    readonly instanceName: string;
+    readonly validate: boolean;
+    readonly dryRuns: boolean;
+}
+/**
+ * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
+ * the GraphQL schema text rebuilt from the resolved manifest; `fields` maps each GraphQL object type's exposed
+ * fields (type name → GraphQL field name) to the stored field or expression its resolvers read;
+ * `deletableTypes` lists the entity types the `deleteEntity` mutation may delete, with aliases
+ * already expanded, and absent means none; `writableFields` maps, per entity type with a
+ * `modify<Type>` mutation, each field of its delta input to the stored property it writes, and
+ * absent means no entity type is writable; `childRecipes` lists, per entity type with a `meta` field,
+ * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
+ * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
+ * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
+ * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
+ * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
+ * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
+ * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
+ * spreads a lens, with the copies that unroll each lens to its depth. Consumed by the configurator
+ * GraphQL system.
+ */
+export interface AssistantManifest {
+    readonly sdl: string;
+    /** Navigation state fields exposed by the schema; absent means none. Values stay in the SDL. */
+    readonly navigationFields?: ReadonlyArray<'navigationState' | 'viewState' | 'toolState'>;
+    readonly fields: Readonly<Record<string, Readonly<Record<string, AssistantFieldSource>>>>;
+    readonly deletableTypes?: readonly string[];
+    readonly writableFields?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
+    readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
+    readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly actions?: Readonly<Record<string, string>>;
+    readonly lenses?: {
+        readonly declarations: string;
+        readonly definitions: string;
+    };
+}

package/dist/domain/application/assistant/assistant-manifest.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/application/assistant/assistant-resolved-manifest.d.ts

@@ -0,0 +1,131 @@
+import type { AssistantFieldOptions, AssistantRecipeGroup } from './assistant-manifest.js';
+/** JSON description of a scalar or recursively nested list, including nullability at each level. */
+export type AssistantValueType = {
+    readonly kind: 'scalar';
+    readonly name: 'Int' | 'Float' | 'String' | 'Boolean' | 'ID' | 'JSON';
+    readonly nonNull: boolean;
+} | {
+    readonly kind: 'list';
+    readonly item: AssistantValueType;
+    readonly nonNull: boolean;
+};
+/** A relation edge resolved against the model at parse time, linked to GraphQL types only during building. */
+export interface AssistantRelationType {
+    readonly kind: 'edge';
+    readonly target: string;
+    readonly cardinality: '1-1' | '0-1' | '0-N' | '1-N';
+}
+/**
+ * A field's source and resolved type, carried in the application bundle without GraphQL instances.
+ * `lenses` names the lenses the field's own declaration on this alias or type tags it with; a field
+ * only inherited from an alias carries none here, since the alias already selects it.
+ */
+export interface AssistantResolvedField {
+    readonly name: string;
+    readonly source: string;
+    readonly type: {
+        readonly kind: 'value';
+        readonly type: AssistantValueType;
+    } | AssistantRelationType;
+    readonly localized: boolean;
+    readonly description?: string;
+    readonly lenses?: readonly string[];
+}
+/** Declared UI state values used to describe the navigation query. */
+export interface AssistantStates {
+    readonly navigationStates: readonly string[];
+    readonly viewStates: readonly string[];
+    readonly toolStates: readonly string[];
+}
+/** Serializable resolved whitelist from which the browser or backend constructs the assistant schema. */
+export interface AssistantResolvedManifest {
+    readonly declarations: AssistantDeclarations;
+    readonly entityTypes: readonly string[];
+    readonly aliases: Readonly<Record<string, readonly string[]>>;
+    readonly exampleType?: string;
+    readonly fields: Readonly<Record<string, readonly AssistantResolvedField[]>>;
+    readonly states: AssistantStates;
+    readonly deletableTypes: readonly string[];
+    readonly writableTypes: readonly AssistantWritableType[];
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
+    readonly actionFields: readonly AssistantResolvedAction[];
+    /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
+    readonly lenses: Readonly<Record<string, {
+        readonly description: string;
+        readonly maxDepth: number;
+    }>>;
+}
+/** Optional mutation input for one stored field, using its exposed name. */
+export interface AssistantWritableField {
+    readonly name: string;
+    readonly property: string;
+    readonly type: AssistantValueType;
+    readonly description?: string;
+}
+/** One entity type's writable fields, in manifest order. */
+export interface AssistantWritableType {
+    readonly entityType: string;
+    readonly fields: readonly AssistantWritableField[];
+}
+/** Description hints resolved from recipe/option entries; no parse context is retained. */
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
+/** Recipe groups and their description hints for one entity type. */
+export interface AssistantResolvedRecipes {
+    readonly groups: readonly AssistantRecipeGroup[];
+    readonly hints: readonly AssistantResolvedHint[];
+}
+/** One options edge, carrying the write-validation contract and schema description hints. */
+export interface AssistantResolvedOptionsEdge {
+    readonly options: AssistantFieldOptions;
+    readonly hints: readonly AssistantResolvedHint[];
+}
+/** An action result field, either an entity edge or a plain JSON-described value. */
+export type AssistantResolvedActionResult = {
+    readonly kind: 'edge';
+    readonly target: string;
+    readonly list: boolean;
+    readonly nullable: boolean;
+    readonly description?: string;
+} | {
+    readonly kind: 'value';
+    readonly type: AssistantValueType;
+    readonly description?: string;
+};
+/** A custom mutation resolved against the declared action, independent of its implementation. */
+export interface AssistantResolvedAction {
+    readonly fieldName: string;
+    readonly actionName: string;
+    readonly description?: string;
+    readonly args: Readonly<Record<string, {
+        readonly type: AssistantValueType;
+        readonly description?: string;
+    }>>;
+    readonly result: Readonly<Record<string, AssistantResolvedActionResult>>;
+}
+/** Immutable, validated declaration bindings retained before alias expansion for session narrowing. */
+export interface AssistantDeclarations {
+    readonly entities: Readonly<Record<string, readonly AssistantDeclaredField[]>>;
+    readonly enumValues: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    readonly deletable: readonly string[];
+    readonly writable: Readonly<Record<string, Readonly<Record<string, AssistantDeclaredWrite>>>>;
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+}
+/** An original field declaration, including metadata needed to reapply inheritance and enum descriptions. */
+export interface AssistantDeclaredField extends AssistantResolvedField {
+    readonly describedByManifest: boolean;
+    readonly enumValues?: readonly string[];
+    readonly valueDescription?: string;
+}
+/** Stored-property types and component bindings, resolved separately for each concrete member. */
+export interface AssistantDeclaredWrite {
+    readonly members: Readonly<Record<string, {
+        readonly exposedDescription?: string;
+        readonly field: AssistantWritableField;
+        readonly options?: AssistantResolvedOptionsEdge;
+    }>>;
+    readonly defaultOptionsName: boolean;
+}

package/dist/domain/application/assistant/assistant-resolved-manifest.js

@@ -0,0 +1 @@
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];

package/dist/domain/application/assistant/assistant-value-type.d.ts

@@ -0,0 +1,9 @@
+import { type GraphQLInputType, type GraphQLOutputType, GraphQLScalarType } from 'graphql';
+import type { AssistantValueType } from './assistant-resolved-manifest.js';
+/**
+ * Opaque scalar for values the assistant schema does not type: objects, custom TypeScript types and
+ * loose unions. A value is plain serializable data and passes through unchanged.
+ */
+export declare const GraphQLJSON: GraphQLScalarType<unknown, unknown>;
+/** Recreates a GraphQL value type from the JSON descriptor, preserving every list and nullability layer. */
+export declare const createAssistantValueType: (descriptor: AssistantValueType) => GraphQLInputType & GraphQLOutputType;

package/dist/domain/application/assistant/assistant-value-type.js

@@ -0,0 +1 @@
+import{GraphQLBoolean as e,GraphQLFloat as n,GraphQLID as t,GraphQLInt as a,GraphQLList as r,GraphQLNonNull as l,GraphQLScalarType as i,GraphQLString as s}from"graphql";export const GraphQLJSON=new i({name:"JSON",description:"Any JSON value, returned unchanged as plain serializable data."});let o={Int:a,Float:n,String:s,Boolean:e,ID:t,JSON:GraphQLJSON};export const createAssistantValueType=e=>{let n="list"===e.kind?new r(createAssistantValueType(e.item)):o[e.name];return e.nonNull?new l(n):n};

package/dist/domain/application/assistant/build-assistant-lenses.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLSchema } from 'graphql';
+import type { AssistantManifest } from './assistant-manifest.js';
+import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+/**
+ * Generates the lens fragments of a resolved manifest for the execution schema compiled from it. A
+ * declared lens becomes one fragment on `AnyDomainEntity`; one that session narrowing left without a
+ * tagged field is dropped, so the agent is never offered a lens that selects nothing. A built-in lens
+ * is present only when the schema has its type. A tagged relation spreads the lens itself in the
+ * declarations, which GraphQL forbids, so the definitions unroll it into copies down to `maxDepth`,
+ * where relations select only `id`. The definitions are checked here against the execution schema,
+ * with every declared lens spread on one entity, so a fault in them fails the build and not the
+ * operations that spread them.
+ */
+export declare const buildAssistantLenses: (resolved: AssistantResolvedManifest, schema: GraphQLSchema) => NonNullable<AssistantManifest['lenses']>;

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -0,0 +1,5 @@
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
+${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
+
+{ ${s} }`),i.filter(t=>t!==e));if(r.length>0)throw Error(`The lens fragments generated from "assistant.lenses" are not valid GraphQL: ${[...new Set(r.map(e=>e.message))].join(" ")}`)}return{declarations:h,definitions:u}};

package/dist/domain/application/assistant/build-assistant-manifest.d.ts

@@ -0,0 +1,4 @@
+import type { AssistantManifest } from './assistant-manifest.js';
+import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+/** Constructs the schema and runtime sources exclusively from serializable resolved data. */
+export declare const buildAssistantManifest: (resolved: AssistantResolvedManifest) => Required<AssistantManifest>;

package/dist/domain/application/assistant/build-assistant-manifest.js

@@ -0,0 +1 @@
+import{GraphQLBoolean as e,GraphQLID as t,GraphQLInputObjectType as n,GraphQLInterfaceType as i,GraphQLList as r,GraphQLNonNull as s,GraphQLObjectType as o,GraphQLSchema as a,GraphQLString as p,printSchema as d,validateSchema as c}from"graphql";import{GraphQLJSON as l,createAssistantValueType as h}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as w}from"./create-assistant-execution-schema.js";let u="AnyDomainEntity",m="RootEntity",f=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],g={section:"childRecipes",mutation:"addChild"},b={section:"replaceRecipes",mutation:"replaceEntity"},j=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],v=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},$=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new s(i);case"0-1":return i;case"0-N":case"1-N":return new s(new r(new s(i)))}},O=(e,n,i)=>{let r={id:{type:new s(t),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new s(p),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let t of e)r[t.name]={type:"edge"===t.type.kind?$(t.type,n):h(t.type.type),description:t.description};return r},E=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),R={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},k={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},I=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),T=({section:e},{groups:t,hints:n},{entityType:i,purpose:o,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new s(new r(new s(a))),description:`The recipe groups for ${o} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${I(n,R,i)}`}}},N=({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},{recipeGroup:a,fieldOption:p})=>new o({name:`${e}Meta`,fields:Object.assign(T(g,t,{entityType:e,purpose:"adding children to",recipeGroup:a}),T(b,n,{entityType:e,purpose:"replacing",recipeGroup:a}),...i.map(({options:{edgeName:t,field:n,validate:i,dryRuns:o},hints:a})=>({[t]:{type:new r(new s(p)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${o?"":" Cannot be dry-run."}${I(a,k,e)}`}})))}),A=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=$=>{var R,k,I,T,S;let D,M,F,W,{entityTypes:x,aliases:C,exampleType:q,fields:G,states:U,deletableTypes:K,writableTypes:P,actionFields:V,optionsEdges:z}=$,Q=Object.fromEntries(Object.entries($.childRecipes).map(([e,t])=>[e,t.groups])),B=Object.fromEntries(Object.entries($.replaceRecipes).map(([e,t])=>[e,t.groups])),H=new Map,J=new Map,L=new Map,X=e=>{let[t,...n]=Object.entries(C).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?J.get(t):void 0)??L.get(e)??Z},Y=e=>J.get(e)??X(e),Z=new i({name:u,description:"Every entity of the configuration.",fields:()=>O(G[u]??[],Y,q)});for(let e of(L.set(u,Z),Object.keys(C)))e!==u&&L.set(e,new i({name:e,interfaces:[Z],fields:()=>O(G[e]??[],Y)}));let _={};for(let e of x){let t=[u,...Object.entries(C).filter(([t,n])=>t!==u&&n.includes(e)).map(([e])=>e)],n=G[e]??[];_[e]=E(n),J.set(e,new o({name:e,interfaces:t.flatMap(e=>L.get(e)??[]),fields:()=>{let t=H.get(e);return{...O(n,Y),...t?{meta:{type:new s(t),description:"What can be done to this entity right now."}}:{}}}}))}let ee=(R=()=>X(L.has(m)?m:u),k=()=>X(u),D=new o({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new s(p),description:"Kind of the problem."},entityId:{type:t,description:"The entity the problem is on, when it is on one."},message:{type:p,description:"The problem as the user would be told it."}}}),new o({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new s(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:R(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new s(new r(new s(k()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new s(new r(new s(t))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new s(new r(new s(p))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new s(new r(new s(D))),description:"Why the change cannot be made; empty when ok is true."}})})),et={recipeGroup:(I=[...Object.keys(Q).length>0?[g.mutation]:[],...Object.keys(B).length>0?[b.mutation]:[]],M=I.join(" or "),F=new o({name:"Recipe",description:`${I.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${I.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new s(p),description:`Pass to ${M} as recipeKey. Valid only for the listing it came from.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Thumbnail shown to the user."},dryRun:{type:ee,description:"What using this recipe would do. Null when it cannot be tried."}}}),new o({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new s(p),description:`Pass to ${M} as recipeGroupId.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},recipes:{type:new s(new r(new s(F)))}}})),fieldOption:new o({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new s(l),description:"The value to write to the field."},name:{type:p,description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Image shown to the user."},color:{type:p,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:ee,description:"What writing this value would do. Null when it cannot be tried."}}})};for(let e of x){let t=j($.childRecipes,e)??{groups:[],hints:[]},n=j($.replaceRecipes,e)??{groups:[],hints:[]},i=j(z,e)??[];(t.groups.length>0||n.groups.length>0||i.length>0)&&H.set(e,N({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i.map(t=>({...t,hints:(C[m]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints}))},et))}let en=new a({query:(T=X(L.has(m)?m:u),S=X(u),W=(e=>{let t={};for(let[n,i,r]of f){let o=e[r];o.length>1&&(t[n]={type:new s(p),description:v(i,o)})}if(0!==Object.keys(t).length)return new o({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(U),new o({name:"Query",fields:{root:{type:new s(T),description:"The root entity of the configuration."},entities:{type:new s(new r(S)),args:{ids:{type:new r(new s(t))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new s(S),description:"The selected entity, or the root entity when nothing is selected."},...W?{navigation:{type:new s(W)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:i,childRecipes:a,replaceRecipes:d,actionFields:c,objectTypes:l,anyDomainEntity:y,targetOutputType:w})=>{let u,m;if(0!==e.length||0!==i.length||0!==Object.keys(a).length||0!==Object.keys(d).length||0!==c.length)return new o({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new s(new r(new s(t))),args:{id:{type:new s(t)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=A(a)).length?{}:{addChild:{type:new s(new r(new s(y))),args:{parentId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(m=A(d)).length?{}:{replaceEntity:{type:new s(new r(new s(y))),args:{entityId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${m.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...i.flatMap(e=>{let i=l.get(e.entityType);return i?[(({entityType:e,fields:i},r)=>{let o=Object.fromEntries(i.map(({name:e,type:t,description:n})=>[e,{type:h(t),description:n}]));return{[`modify${e}`]:{type:r,args:{id:{type:new s(t)},delta:{type:new s(new n({name:`${e}Delta`,fields:o}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,i)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new s(new o({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let o=t?new r(new s(i(e))):i(e);return n?o:new s(o)})(t,w):h(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:h(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:P,childRecipes:Q,replaceRecipes:B,actionFields:V,objectTypes:J,anyDomainEntity:X(u),targetOutputType:Y}),types:[...L.values(),...J.values()]}),ei=c(en);if(ei.length>0)throw Error(ei.map(e=>e.message).join(" "));let er=d(en);return{sdl:er,navigationFields:f.filter(([,,e])=>U[e].length>1).map(([e])=>e),fields:_,deletableTypes:K,writableFields:Object.fromEntries(P.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:Q,replaceRecipes:B,fieldOptions:Object.fromEntries(x.flatMap(e=>{let t=j(z,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),actions:Object.fromEntries(V.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y($,w(er))}};

package/dist/domain/application/assistant/create-assistant-execution-schema.d.ts

@@ -0,0 +1,32 @@
+import { type GraphQLSchema } from 'graphql';
+/** One entity type or alias exposing a field, with the field's type as the assistant schema prints it. */
+export interface AssistantFieldExposure {
+    readonly typeName: string;
+    readonly type: string;
+}
+/**
+ * Entity types or aliases expose one field name in shapes no selection can hold together: a single
+ * entity, a list of entities and a plain value cannot share a name. GraphQL rejects every operation
+ * that selects the field on both, and no common type exists to widen them to. `exposures` lists the
+ * aliases and types that declare the field, without the members that only repeat an alias's field.
+ */
+export declare class AssistantFieldClashError extends Error {
+    readonly fieldName: string;
+    readonly exposures: readonly AssistantFieldExposure[];
+    constructor(fieldName: string, exposures: readonly AssistantFieldExposure[]);
+}
+/**
+ * Compiles the schema operations are validated and executed against from the assistant SDL the agent
+ * reads. GraphQL requires fields selected under one name to have the same type, nullability included,
+ * even on entity types that can never be the same entity, so a lens or a hand-written selection that
+ * reaches such a field on two types would be rejected although its result is unambiguous. The
+ * execution schema therefore widens the type of every field name that entity types and aliases
+ * expose with different types, and leaves everything else as it is. It accepts every operation the
+ * SDL accepts and some the SDL would reject; the SDL stays the precise description of the data.
+ * Accepted: a widened field no longer enforces its SDL type on the value it resolves to. A null in a
+ * field the SDL declares non-null is returned as null instead of failing the operation, and a field
+ * widened to `JSON` is returned as it is, without the coercion of its scalar. Values that match their
+ * SDL type, which is every value a valid configuration holds, give the same result. Throws
+ * {@link AssistantFieldClashError} for the shapes nothing can widen.
+ */
+export declare const createAssistantExecutionSchema: (sdl: string) => GraphQLSchema;

package/dist/domain/application/assistant/create-assistant-execution-schema.js

@@ -0,0 +1 @@
+import{Kind as e,buildASTSchema as t,parse as n,print as a}from"graphql";let i="AnyDomainEntity",l="JSON",s=new Set(["Int","Float","String","Boolean","ID",l]);export class AssistantFieldClashError extends Error{fieldName;exposures;constructor(e,t){super(`The field "${e}" cannot be selected on every entity type that has it: ${t.map(({typeName:t,type:n})=>`${t}.${e} is ${n}`).join(", ")}.`),this.fieldName=e,this.exposures=t,this.name="AssistantFieldClashError"}}let r=t=>(t.kind===e.OBJECT_TYPE_DEFINITION||t.kind===e.INTERFACE_TYPE_DEFINITION)&&(t.name.value===i||(t.interfaces??[]).some(({name:e})=>e.value===i)),o=t=>t.kind===e.NON_NULL_TYPE?t.type:t,m=t=>t.kind===e.NAMED_TYPE?t.name.value:m(t.type),u=e=>a(e).replace(m(e),""),p={kind:e.NAMED_TYPE,name:{kind:e.NAME,value:l}},d=(t,n)=>{let i=n.map(({type:e})=>e);if(1===new Set(i.map(e=>a(e))).size)return;let l=i.map(e=>s.has(m(e)));if(l.every(Boolean))return 1===new Set(i.map(e=>a(o(e)))).size?"nullable":"json";if(!l.some(Boolean)){if(1===new Set(i.map(u)).size)return;if(i.every(t=>o(t).kind===e.NAMED_TYPE))return"nullable"}throw new AssistantFieldClashError(t,n.filter(({inherited:e})=>!e).map(({typeName:e,type:t})=>({typeName:e,type:a(t)})))};export const createAssistantExecutionSchema=a=>t((t=>{let n=t.definitions.filter(r),a=(e,t)=>n.some(n=>n.name.value===e&&(n.fields??[]).some(e=>e.name.value===t)),i=new Map;for(let e of n)for(let t of e.fields??[])i.set(t.name.value,[...i.get(t.name.value)??[],{typeName:e.name.value,type:t.type,inherited:(e.interfaces??[]).some(({name:e})=>a(e.value,t.name.value))}]);let s=new Map;for(let[e,t]of i){let n=d(e,t);n&&s.set(e,n)}let m=e=>{let t=s.get(e.name.value);return t?{...e,type:"json"===t?p:o(e.type)}:e},u=t.definitions.map(e=>r(e)?{...e,fields:e.fields?.map(m)}:e),f=u.some(t=>t.kind===e.SCALAR_TYPE_DEFINITION&&t.name.value===l),E=[...s.values()].includes("json");return{...t,definitions:E&&!f?[...u,{kind:e.SCALAR_TYPE_DEFINITION,name:{kind:e.NAME,value:l}}]:u}})(n(a)));