@salsita-ai/sdk 0.50.0-develop.da8d27f5d7 → 0.50.0-develop.dfac20c66b

package/dist/application-spec/generate-application/code/templates/{common → skills}/sdk-content.d.ts

@@ -25,6 +25,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
     readonly projectStructure: `## Project Structure
 - \`spec/\` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)
 - \`src/expressions/\` — Computed/derived entity properties (\`phx.domain.implementCustomExpressions()\`)
+- \`src/actions/\` — Domain operations declared under \`actions:\` in the spec (\`phx.domain.implementActions()\`), run by controls and exposed to the assistant
 - \`src/invariants/\` — Business rule constraints (\`phx.domain.implementCustomInvariants()\`)
 - \`src/transformers/\` — Automatic state fixers (\`phx.frontend.transformerBuilder\`)
 - \`src/components/\` — ECS system components (\`phx.domain.attachComponent.withEntity()\`)
@@ -48,6 +49,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
     /** Expressions, invariants, transformers, components, webhooks, and filters at a glance. */
     readonly keyPatterns: `## Key Patterns
 - Expressions = computed properties on entities (prefix: \`$\`), implemented per-entity in src/expressions/
+- Actions = named domain operations (\`actions:\` in YAML with \`params\` and \`result\` schemas), implemented in src/actions/, prepared through \`actionSystem.prepareAction()\` and exposed as assistant mutations through \`assistant.actions\`
 - Invariants = validation rules returning violations, static or dynamic
 - Transformers = auto-fixers maintaining consistency after state changes
 - Components defined in YAML with \`$read\`/\`$bind\` bindings, or custom in src/components/ using attachComponent builder
@@ -63,7 +65,7 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
 - Underscore folders (_shared/, _utils/) are NOT auto-imported`;
     /** The default-export rule of the SDK auto-import system. */
     readonly exportRules: `## Export Rules
-All files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`;
+All files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`;
     /** Which components and handlers are bundled into the webhook. */
     readonly webhookMembership: `## Webhook Membership
 - User-authored components, admin components, and handlers are frontend-only by default.
@@ -76,6 +78,27 @@ All files in src/expressions/, src/invariants/, src/transformers/, src/component
 - \`.phoenix/\` directory — completely regenerated on each build
 - \`tsconfig.json\`, \`eslint.config.js\`, \`prettier.config.js\`, \`.prettierignore\`, \`.linguirc\`, \`.nvmrc\`
 - \`src/locales/\` .ts files — compiled from .po files`;
+    /** When and how a deployed domain model gets a new version and a migration, with the recipe for replacing the starter. */
+    readonly modelVersioning: `## Version the Domain Model Once It Is Deployed
+A deployed model version cannot change, because saved configurations depend on it. \`pnpm phoenix deploy\` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: \`model.latest\` is always the highest numbered version plus one, so a spec with only \`latest\` is v1, and \`applicationVersion\` plays no part. \`pnpm phoenix dev\` accepts every model change, so a working preview does not show that the deploy will pass.
+
+To change a model that has been deployed as v<N>:
+1. Keep the deployed model, unchanged, as \`model.v<N>\` in the spec. A file of its own, such as \`spec/model-v<N>.yaml\`, keeps \`latest\` readable.
+2. Make the change in \`model.latest\`, which is now v<N+1>.
+3. Add \`src/migrations/v<N+1>.ts\` exporting \`migrateToV<N+1>\`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; \`ModelV<N>\` and \`ModelV<N+1>\` are generated global namespaces.
+
+The admin model is versioned on its own, under \`src/admin/migrations/\`, with its types in \`AdminV<N>\`.
+
+**Replacing the starter.** When the first deployment of the workspace was the starter, its \`Box\` model is v1 in production. When the real model replaces it, keep the starter's model as \`model.v1\` and define the real model in \`latest\`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the \`initialDomainEntities\` of its preset, and drops the boxes:
+\`\`\`typescript
+// src/migrations/v2.ts
+import type { Migration } from '@salsita-ai/sdk/domain'
+
+export const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [
+  // the entities of the new model's preset
+]
+\`\`\`
+An entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (\`Box-1\`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read \`docs/phoenix/migrations.mdx\` before writing any other migration.`;
     /** How to find and read SDK documentation from the CLI. */
     readonly sdkDocumentation: `## SDK Documentation
 

package/dist/application-spec/generate-application/code/templates/skills/sdk-content.js

@@ -0,0 +1,67 @@
+export const sdkGuidanceSections={projectIntro:`## Phoenix Configurator Project
+
+Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`,buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/actions/` — Domain operations declared under `actions:` in the spec (`phx.domain.implementActions()`), run by controls and exposed to the assistant\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Actions = named domain operations (`actions:` in YAML with `params` and `result` schemas), implemented in src/actions/, prepared through `actionSystem.prepareAction()` and exposed as assistant mutations through `assistant.actions`\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
+- Components: PascalCase (.tsx)
+- Utilities: kebab-case (.ts)
+- Expressions: entity-name.ts
+- Migrations: v*.ts (sequential)
+- Specs: kebab-case.yaml
+- Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:`## Export Rules
+All files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.`,webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files — compiled from .po files",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
+
+Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
+
+**Prerequisites:** same as screenshot (dev server running + browser open)
+
+**Options:**
+- \`--output, -o\` — Output file path (prints to stdout if omitted)
+- \`--pretty\` — Pretty-print JSON (default: true)
+- \`--port\` — WebSocket server port (default: 3020)
+
+**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties
+
+**Example:** \`pnpm phoenix inspect:data -o ./data.json\`
+
+**Tips:** Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:data | head -30\`).
+
+**Use cases:** AI agent context, debugging published/session/access data`,inspectScene:`## Inspect: Scene
+
+Get the current Three.js scene graph as JSON via \`pnpm phoenix inspect:scene\`.
+
+**Prerequisites:** same as screenshot (dev server running + browser open)
+
+**Options:**
+- \`--output, -o\` — Output file path (prints to stdout if omitted)
+- \`--pretty\` — Pretty-print JSON (default: true)
+- \`--port\` — WebSocket server port (default: 3020)
+
+**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.
+
+**Example:** \`pnpm phoenix inspect:scene -o ./scene.json\`
+
+**Tips:** Scene graphs can be large. Pipe through \`head\`/\`tail\` for partial output.
+
+**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting`,playwrightMcpSetup:`## Playwright MCP Setup (for AI agents)
+
+To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to \`~/.claude/.mcp.json\`:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--headed",
+        "--launch-options",
+        "{\\"args\\":[\\"--use-gl=swiftshader\\",\\"--enable-webgl\\",\\"--ignore-gpu-blocklist\\"]}"
+      ]
+    }
+  }
+}
+\`\`\`
+
+Key flags:
+- \`--headed\` — visible browser (required for GPU rendering)
+- \`--use-gl=swiftshader\` — software GPU fallback for environments without a physical GPU
+- \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`};

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.d.ts

@@ -2,6 +2,7 @@ import { Branded } from '@salsita-ai/common/utils';
 import type { ImportedTransformer } from '#package/domain';
 import type { RuntimeReferenceStore } from '../../../caching/index.js';
 import type { ApplicationSpec } from '../../../parse-application-files/index.js';
+import { ActionsRuntime } from '../sections/actions-runtime.js';
 import { AssistantRuntime } from '../sections/assistant-runtime.js';
 import { ComponentOptics } from '../sections/component-optic.js';
 import { type ExpressionImplementations, ExpressionRuntime, type InvariantImplementations, type MissingExpression } from '../sections/expression-runtime.js';
@@ -20,6 +21,7 @@ export type ConfiguratorRuntime = Branded<'ConfiguratorRuntime', {
     readonly themeRuntime: ThemeRuntime;
     readonly transformersRuntime: TransformersRuntime;
     readonly assistantRuntime: AssistantRuntime;
+    readonly actionsRuntime: ActionsRuntime;
 }>;
 export type ConfiguratorRuntimeResult = {
     readonly ok: true;

package/dist/application-spec/generate-application/runtime/configurator-runtime/configurator-runtime.js

@@ -1 +1 @@
-import{Branded as t}from"@salsita-ai/common/utils";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as o}from"../sections/component-optic.js";import{ExpressionRuntime as r}from"../sections/expression-runtime.js";import{PresetRuntime as s}from"../sections/preset-runtime.js";import{ThemeRuntime as i}from"../sections/theme-runtime.js";import{TransformersRuntime as n}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as m}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as u}from"./states-runtime.js";export const ConfiguratorRuntime=(p,c,f,a,g)=>{let R=m(p.configurator,c),j=r(p.configurator,c,f,"configuratorExpressionRuntime",g);return j.ok?{ok:!0,runtime:t({modelRuntime:R,componentOptics:o(c,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:R}),presetRuntime:s(c,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:u(p,c),expressionRuntime:j.runtime,themeRuntime:i(p,c),transformersRuntime:n(p,c,a),assistantRuntime:e(p,c)})}:{ok:!1,missingExpressions:j.missing}};
+import{Branded as t}from"@salsita-ai/common/utils";import{ActionsRuntime as o}from"../sections/actions-runtime.js";import{AssistantRuntime as e}from"../sections/assistant-runtime.js";import{ComponentOptics as r}from"../sections/component-optic.js";import{ExpressionRuntime as s}from"../sections/expression-runtime.js";import{PresetRuntime as i}from"../sections/preset-runtime.js";import{ThemeRuntime as n}from"../sections/theme-runtime.js";import{TransformersRuntime as m}from"../sections/transformers-runtime.js";import{ConfiguratorModelRuntime as u}from"./configurator-model-runtime.js";import{ConfiguratorStatesRuntime as c}from"./states-runtime.js";export const ConfiguratorRuntime=(p,a,f,g,R)=>{let j=u(p.configurator,a),x=s(p.configurator,a,f,"configuratorExpressionRuntime",R);return x.ok?{ok:!0,runtime:t({modelRuntime:j,componentOptics:r(a,{components:p.configurator.components,referenceScope:"configuratorRuntime/componentOptics",modelRuntime:j}),presetRuntime:i(a,{referenceScope:"configuratorRuntime/presetRuntime",presets:p.configurator.presets.presets}),statesRuntime:c(p,a),expressionRuntime:x.runtime,themeRuntime:n(p,a),transformersRuntime:m(p,a,g),assistantRuntime:e(p,a),actionsRuntime:o(p.configurator.actions,a)})}:{ok:!1,missingExpressions:x.missing}};

package/dist/application-spec/generate-application/runtime/sections/actions-runtime.d.ts

@@ -0,0 +1,14 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ActionDefinitions } from '#package/domain';
+import type { RuntimeReferenceStore } from '../../../caching/index.js';
+import type { Actions } from '../../../parse-application-files/index.js';
+/**
+ * The declared actions as the runtime spec slice holds them, with change tracking: the definitions
+ * are rebuilt only when their declaration changes, so a hot reload of an unrelated section keeps
+ * the action system's compiled validators.
+ */
+export type ActionsRuntime = Branded<'ActionsRuntime', {
+    readonly definitions: ActionDefinitions;
+    readonly changed: boolean;
+}>;
+export declare const ActionsRuntime: (actions: Actions, referenceStore: RuntimeReferenceStore) => ActionsRuntime;

package/dist/application-spec/generate-application/runtime/sections/actions-runtime.js

@@ -0,0 +1 @@
+import i from"lodash-es/isEqual.js";import{Branded as e}from"@salsita-ai/common/utils";export const ActionsRuntime=(t,n)=>{let o=n.createBuilder("configuratorRuntime/actions",{build:i=>i.definition,getKey:i=>i.definition.name,compare:(e,t)=>i(e.definition,t.definition)}),a=!1,r=new Set,d={};for(let i of t.values()){let e={definition:{name:String(i.name),...void 0===i.description?{}:{description:i.description},params:i.paramsSchema}},t=o.build(e);t.changed&&(a=!0),r.add(o.getKey(e)),d[t.output.name]=t.output}return o.cleanup(r)&&(a=!0),e({definitions:d,changed:a})};

package/dist/application-spec/generate-application/runtime/sections/index.d.ts

@@ -1,3 +1,4 @@
+export { ActionsRuntime } from './actions-runtime.js';
 export { AssistantRuntime } from './assistant-runtime.js';
 export { ComponentOptics, type ComponentOptic } from './component-optic.js';
 export { DataRuntime } from './data-runtime.js';

package/dist/application-spec/generate-application/runtime/sections/index.js

@@ -1 +1 @@
-export{AssistantRuntime}from"./assistant-runtime.js";export{ComponentOptics}from"./component-optic.js";export{DataRuntime}from"./data-runtime.js";export{ExpressionRuntime}from"./expression-runtime.js";export{PresetRuntime}from"./preset-runtime.js";export{ThemeRuntime}from"./theme-runtime.js";export{TransformersRuntime}from"./transformers-runtime.js";export{evaluateStaticMemoEvalPlan,generateMemoEvalPlanRuntime}from"./generate-memo-eval-plan-runtime.js";export{evaluateReflectionConstants,findReflectionConstants}from"./reflection-constants-runtime.js";
+export{ActionsRuntime}from"./actions-runtime.js";export{AssistantRuntime}from"./assistant-runtime.js";export{ComponentOptics}from"./component-optic.js";export{DataRuntime}from"./data-runtime.js";export{ExpressionRuntime}from"./expression-runtime.js";export{PresetRuntime}from"./preset-runtime.js";export{ThemeRuntime}from"./theme-runtime.js";export{TransformersRuntime}from"./transformers-runtime.js";export{evaluateStaticMemoEvalPlan,generateMemoEvalPlanRuntime}from"./generate-memo-eval-plan-runtime.js";export{evaluateReflectionConstants,findReflectionConstants}from"./reflection-constants-runtime.js";

package/dist/application-spec/parse-application-files/categorize/categorize-files.d.ts

@@ -3,7 +3,7 @@ import { type RuntimeReferenceStore } from '../../caching/index.js';
 import type { ParseContext, RawProjectFiles, TextFile } from '../../core/index.js';
 import { type ModuleAnalysis, type ModuleAnalyzer, type WebhookMembership } from './module-analysis.js';
 /** Known file categories used for path-based sorting. */
-export type FileCategory = 'spec' | 'expressions' | 'handlers' | 'elements' | 'transformers' | 'components' | 'invariants' | 'migrations' | 'adminMigrations' | 'adminExpressions' | 'adminInvariants' | 'adminComponents' | 'adminElements' | 'webhooks' | 'locales' | 'mockTemplates' | 'projectFiles' | 'customCode';
+export type FileCategory = 'spec' | 'expressions' | 'actions' | 'handlers' | 'elements' | 'transformers' | 'components' | 'invariants' | 'migrations' | 'adminMigrations' | 'adminExpressions' | 'adminInvariants' | 'adminComponents' | 'adminElements' | 'webhooks' | 'locales' | 'mockTemplates' | 'projectFiles' | 'customCode';
 /**
  * A text file categorized by path pattern, with dep-aware change tracking.
  *
@@ -32,6 +32,8 @@ export type CategorizedFiles = Branded<'CategorizedFiles', {
     readonly specChanged: boolean;
     readonly expressions: readonly CategorizedFile[];
     readonly expressionsChanged: boolean;
+    readonly actions: readonly CategorizedFile[];
+    readonly actionsChanged: boolean;
     readonly handlers: readonly CategorizedFile[];
     readonly handlersChanged: boolean;
     readonly elements: readonly CategorizedFile[];

package/dist/application-spec/parse-application-files/categorize/categorize-files.js

@@ -1 +1 @@
-import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as a}from"../../errors/index.js";import{findWebhookHandlerRegistration as i}from"./module-analysis.js";import{findWebhookSafetyViolation as t}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let r=e=>/\/_[^/]+\//.test(e),m=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],l=new Set(["package.json",".gitignore","CLAUDE.md",".cursor/rules/phoenix.mdc"]),d=new Set(["migrations","adminMigrations"]),p=m.filter(({path:e,key:n})=>e.startsWith("src/")&&d.has(n)),c=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},h=/\.(ts|tsx|js|jsx)$/,f=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=i(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(i,d,g,u)=>{let k={spec:[],expressions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},b=[];for(let e of i.files){if("text"!==e.kind)continue;if(r(e.name)){k.customCode.push({file:e,category:"customCode"});continue}if(l.has(e.name)){k.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of m)if(e.name.startsWith(s)){k[o].push({file:e,category:o}),n=!0;break}n||b.push(e.name)}for(let e of b)e.startsWith("src/")&&g.error(o.UNKNOWN_SRC_PATH,a.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of p)for(let s of k[n])c(s.file.name,e)&&g.error(o.INVALID_SUBDIRECTORY,a.INVALID_SUBDIRECTORY(s.file.name,e));if(k.webhooks.length>0&&!k.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name)&&g.error(o.MISSING_WEBHOOK_INDEX,a.MISSING_WEBHOOK_INDEX()),g.hasErrors)return;let C=[];for(let e of Object.values(k))for(let n of e)C.push(n.file.name);let v=s(i,C),{analyzer:x,logger:E}=u,y=d.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:x(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),I=new Set,w=e=>{if(!h.test(e.name))return;I.add(e.name);let n=y.build({name:e.name,content:e.content}).output;return void 0!==n.error?void g.error(o.MODULE_ANALYSIS_FAILED,a[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},S={},j={};for(let[e,s]of Object.entries(k)){let o=d.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),a=new Set;S[e]=s.map(e=>{let s=v[e.file.name]??{deps:[],hash:""},{changed:i}=o.build({name:e.file.name,depHash:s.hash});a.add(e.file.name);let t=w(e.file),r=void 0===t?void 0:f(e.category,t);return void 0!==r&&E.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:i,analysis:t,webhookMembership:r?.membership})}),j[e]=o.cleanup(a)}y.cleanup(I);let _=(e,n)=>n.some(e=>e.changed)||!0===j[e],F=d.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:i.envs}),M=n({spec:S.spec,specChanged:_("spec",S.spec),expressions:S.expressions,expressionsChanged:_("expressions",S.expressions),handlers:S.handlers,handlersChanged:_("handlers",S.handlers),elements:S.elements,elementsChanged:_("elements",S.elements),transformers:S.transformers,transformersChanged:_("transformers",S.transformers),components:S.components,componentsChanged:_("components",S.components),invariants:S.invariants,invariantsChanged:_("invariants",S.invariants),migrations:S.migrations,migrationsChanged:_("migrations",S.migrations),adminMigrations:S.adminMigrations,adminMigrationsChanged:_("adminMigrations",S.adminMigrations),adminExpressions:S.adminExpressions,adminExpressionsChanged:_("adminExpressions",S.adminExpressions),adminInvariants:S.adminInvariants,adminInvariantsChanged:_("adminInvariants",S.adminInvariants),adminComponents:S.adminComponents,adminComponentsChanged:_("adminComponents",S.adminComponents),adminElements:S.adminElements,adminElementsChanged:_("adminElements",S.adminElements),webhooks:S.webhooks,webhooksChanged:_("webhooks",S.webhooks),locales:S.locales,localesChanged:_("locales",S.locales),mockTemplates:S.mockTemplates,mockTemplatesChanged:_("mockTemplates",S.mockTemplates),projectFiles:S.projectFiles,projectFilesChanged:_("projectFiles",S.projectFiles),customCode:S.customCode,customCodeChanged:_("customCode",S.customCode),envs:F.output,envsChanged:F.changed}),O=buildProjectFileIndex(M);for(let e of O.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=t(e,O);void 0!==n&&g.error(o.WEBHOOK_UNSAFE_IMPORT,a[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return M};
+import e from"lodash-es/isEqual.js";import{Branded as n}from"@salsita-ai/common/utils";import{computeFileDepHashes as s}from"../../caching/index.js";import{DiagnosticCode as o,diagnosticMessages as a}from"../../errors/index.js";import{findWebhookHandlerRegistration as i}from"./module-analysis.js";import{findWebhookSafetyViolation as t}from"./webhook-safety.js";export const buildProjectFileIndex=e=>new Map([...e.spec,...e.expressions,...e.actions,...e.handlers,...e.elements,...e.transformers,...e.components,...e.invariants,...e.migrations,...e.adminMigrations,...e.adminExpressions,...e.adminInvariants,...e.adminComponents,...e.adminElements,...e.webhooks,...e.locales,...e.mockTemplates,...e.projectFiles,...e.customCode].map(e=>[e.file.name,e]));let r=e=>/\/_[^/]+\//.test(e),m=[{path:"spec/",key:"spec"},{path:"src/admin/expressions/",key:"adminExpressions"},{path:"src/admin/invariants/",key:"adminInvariants"},{path:"src/admin/components/",key:"adminComponents"},{path:"src/admin/elements/",key:"adminElements"},{path:"src/admin/migrations/",key:"adminMigrations"},{path:"src/expressions/",key:"expressions"},{path:"src/actions/",key:"actions"},{path:"src/handlers/",key:"handlers"},{path:"src/elements/",key:"elements"},{path:"src/transformers/",key:"transformers"},{path:"src/components/",key:"components"},{path:"src/invariants/",key:"invariants"},{path:"src/migrations/",key:"migrations"},{path:"src/webhooks/",key:"webhooks"},{path:"src/locales/",key:"locales"},{path:"mocks/",key:"mockTemplates"}],l=new Set(["package.json",".gitignore","CLAUDE.md",".cursor/rules/phoenix.mdc"]),d=new Set(["migrations","adminMigrations"]),c=m.filter(({path:e,key:n})=>e.startsWith("src/")&&d.has(n)),p=(e,n)=>{let s=e.slice(n.length).split("/");return!(s.length<=1)&&s.slice(0,-1).some(e=>!e.startsWith("_"))},h=/\.(ts|tsx|js|jsx)$/,f=(e,n)=>{if("components"===e||"adminComponents"===e)return n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (no 'use webhook' directive)"};if("handlers"===e){let e=i(n);return void 0!==e?{membership:"named-handler",logSuffix:`webhook (the ${e} registration)`}:n.hasUseWebhookDirective?{membership:"pinned",logSuffix:"webhook ('use webhook' directive)"}:{membership:"frontend",logSuffix:"frontend only (not a named handler or pin)"}}};export const CategorizedFiles=(i,d,g,u)=>{let k={spec:[],expressions:[],actions:[],handlers:[],elements:[],transformers:[],components:[],invariants:[],migrations:[],adminMigrations:[],adminExpressions:[],adminInvariants:[],adminComponents:[],adminElements:[],webhooks:[],locales:[],mockTemplates:[],projectFiles:[],customCode:[]},b=[];for(let e of i.files){if("text"!==e.kind)continue;if(r(e.name)){k.customCode.push({file:e,category:"customCode"});continue}if(l.has(e.name)){k.projectFiles.push({file:e,category:"projectFiles"});continue}let n=!1;for(let{path:s,key:o}of m)if(e.name.startsWith(s)){k[o].push({file:e,category:o}),n=!0;break}n||b.push(e.name)}for(let e of b)e.startsWith("src/")&&g.error(o.UNKNOWN_SRC_PATH,a.UNKNOWN_SRC_PATH(e));for(let{path:e,key:n}of c)for(let s of k[n])p(s.file.name,e)&&g.error(o.INVALID_SUBDIRECTORY,a.INVALID_SUBDIRECTORY(s.file.name,e));if(k.webhooks.length>0&&!k.webhooks.some(e=>"src/webhooks/index.ts"===e.file.name)&&g.error(o.MISSING_WEBHOOK_INDEX,a.MISSING_WEBHOOK_INDEX()),g.hasErrors)return;let C=[];for(let e of Object.values(k))for(let n of e)C.push(n.file.name);let v=s(i,C),{analyzer:x,logger:y}=u,E=d.createBuilder("categorizedFiles/moduleAnalysis",{build:e=>{try{return{analysis:x(e.name,e.content)}}catch(e){return{error:e instanceof Error?e.message:String(e)}}},getKey:e=>e.name,compare:(e,n)=>e.content===n.content}),I=new Set,w=e=>{if(!h.test(e.name))return;I.add(e.name);let n=E.build({name:e.name,content:e.content}).output;return void 0!==n.error?void g.error(o.MODULE_ANALYSIS_FAILED,a[o.MODULE_ANALYSIS_FAILED](e.name,n.error)):n.analysis},S={},j={};for(let[e,s]of Object.entries(k)){let o=d.createBuilder(`categorizedFiles/${e}`,{build:e=>e,getKey:e=>e.name,compare:(e,n)=>e.depHash===n.depHash}),a=new Set;S[e]=s.map(e=>{let s=v[e.file.name]??{deps:[],hash:""},{changed:i}=o.build({name:e.file.name,depHash:s.hash});a.add(e.file.name);let t=w(e.file),r=void 0===t?void 0:f(e.category,t);return void 0!==r&&y.debug(`Webhook membership: ${e.file.name} -> ${r.logSuffix}`),n({file:e.file,category:e.category,deps:s.deps,depHash:s.hash,changed:i,analysis:t,webhookMembership:r?.membership})}),j[e]=o.cleanup(a)}E.cleanup(I);let _=(e,n)=>n.some(e=>e.changed)||!0===j[e],F=d.createBuilder("categorizedFiles/envs",{build:e=>e.envs,getKey:()=>"singleton",compare:(n,s)=>e(n.envs,s.envs)}).build({envs:i.envs}),M=n({spec:S.spec,specChanged:_("spec",S.spec),expressions:S.expressions,expressionsChanged:_("expressions",S.expressions),actions:S.actions,actionsChanged:_("actions",S.actions),handlers:S.handlers,handlersChanged:_("handlers",S.handlers),elements:S.elements,elementsChanged:_("elements",S.elements),transformers:S.transformers,transformersChanged:_("transformers",S.transformers),components:S.components,componentsChanged:_("components",S.components),invariants:S.invariants,invariantsChanged:_("invariants",S.invariants),migrations:S.migrations,migrationsChanged:_("migrations",S.migrations),adminMigrations:S.adminMigrations,adminMigrationsChanged:_("adminMigrations",S.adminMigrations),adminExpressions:S.adminExpressions,adminExpressionsChanged:_("adminExpressions",S.adminExpressions),adminInvariants:S.adminInvariants,adminInvariantsChanged:_("adminInvariants",S.adminInvariants),adminComponents:S.adminComponents,adminComponentsChanged:_("adminComponents",S.adminComponents),adminElements:S.adminElements,adminElementsChanged:_("adminElements",S.adminElements),webhooks:S.webhooks,webhooksChanged:_("webhooks",S.webhooks),locales:S.locales,localesChanged:_("locales",S.locales),mockTemplates:S.mockTemplates,mockTemplatesChanged:_("mockTemplates",S.mockTemplates),projectFiles:S.projectFiles,projectFilesChanged:_("projectFiles",S.projectFiles),customCode:S.customCode,customCodeChanged:_("customCode",S.customCode),envs:F.output,envsChanged:F.changed}),O=buildProjectFileIndex(M);for(let e of O.values()){if("pinned"!==e.webhookMembership&&"named-handler"!==e.webhookMembership)continue;let n=t(e,O);void 0!==n&&g.error(o.WEBHOOK_UNSAFE_IMPORT,a[o.WEBHOOK_UNSAFE_IMPORT](n.fileName,n.inclusionReason,n.importer,n.specifier))}return M};

package/dist/application-spec/parse-application-files/merge/index.d.ts

@@ -1,4 +1,5 @@
 export * from './classified-spec-file.js';
+export * from './merged-actions.js';
 export * from './merged-admin-components.js';
 export * from './merged-admin-expressions.js';
 export * from './merged-admin-invariants.js';

package/dist/application-spec/parse-application-files/merge/index.js

@@ -1 +1 @@
-export*from"./classified-spec-file.js";export*from"./merged-admin-components.js";export*from"./merged-admin-expressions.js";export*from"./merged-admin-invariants.js";export*from"./merged-admin-states.js";export*from"./merged-admin-model.js";export*from"./merged-components.js";export*from"./merged-configurator-states.js";export*from"./merged-defaults.js";export*from"./merged-model.js";export*from"./merged-admin-pages.js";export*from"./merged-admin-presets.js";export*from"./merged-admin-relations.js";export*from"./merged-assistant.js";export*from"./merged-budgets.js";export*from"./merged-data-schemas.js";export*from"./merged-data-spec.js";export*from"./merged-expressions.js";export*from"./merged-presets.js";export*from"./merged-relations.js";export*from"./merged-spec.js";export*from"./merged-theme.js";export*from"./merged-ui.js";export*from"./merged-transformers.js";export*from"./merged-app-metadata.js";export*from"./merged-infra.js";export*from"./merged-invariants.js";export*from"./merged-chunks.js";
+export*from"./classified-spec-file.js";export*from"./merged-actions.js";export*from"./merged-admin-components.js";export*from"./merged-admin-expressions.js";export*from"./merged-admin-invariants.js";export*from"./merged-admin-states.js";export*from"./merged-admin-model.js";export*from"./merged-components.js";export*from"./merged-configurator-states.js";export*from"./merged-defaults.js";export*from"./merged-model.js";export*from"./merged-admin-pages.js";export*from"./merged-admin-presets.js";export*from"./merged-admin-relations.js";export*from"./merged-assistant.js";export*from"./merged-budgets.js";export*from"./merged-data-schemas.js";export*from"./merged-data-spec.js";export*from"./merged-expressions.js";export*from"./merged-presets.js";export*from"./merged-relations.js";export*from"./merged-spec.js";export*from"./merged-theme.js";export*from"./merged-ui.js";export*from"./merged-transformers.js";export*from"./merged-app-metadata.js";export*from"./merged-infra.js";export*from"./merged-invariants.js";export*from"./merged-chunks.js";

package/dist/application-spec/parse-application-files/merge/merged-actions.d.ts

@@ -0,0 +1,11 @@
+import { Branded } from '@salsita-ai/common/utils';
+import type { ParseContext } from '../../core/index.js';
+import type { RawActions } from '../raw-spec/index.js';
+import type { ClassifiedSpecFile } from './classified-spec-file.js';
+/**
+ * Merged actions from all spec files; an action name declared in two files is a merge conflict.
+ * Actions belong to the configurator domain, so an `actions` block in an admin spec file is reported
+ * rather than merged.
+ */
+export type MergedActions = Branded<'MergedActions', RawActions>;
+export declare const MergedActions: (files: readonly ClassifiedSpecFile[], ctx: ParseContext) => MergedActions;

package/dist/application-spec/parse-application-files/merge/merged-actions.js

@@ -0,0 +1 @@
+import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as n,diagnosticMessages as o}from"../../errors/index.js";export const MergedActions=(t,i)=>{let r={},a={};for(let e of t)if(e.content.actions){if(e.isAdmin){i.inFile(e.name).at("actions").error(n.ACTIONS_IN_ADMIN_FILE,o.ACTIONS_IN_ADMIN_FILE(e.name));continue}for(let[n,o]of Object.entries(e.content.actions)){let t=a[n];if(t){i.error("MERGE_CONFLICT",`Action "${n}" is declared in both "${t}" and "${e.name}". Each action can only be declared once. Keep one declaration and remove the other.`);continue}r[n]=o,a[n]=e.name}}return e(r)};

package/dist/application-spec/parse-application-files/merge/merged-spec.d.ts

@@ -1,6 +1,7 @@
 import { Branded } from '@salsita-ai/common/utils';
 import type { ParseContext } from '../../core/index.js';
 import type { ResolvedSpecFiles } from '../resolve/index.js';
+import { MergedActions } from './merged-actions.js';
 import { MergedAdminPages } from './merged-admin-pages.js';
 import { MergedAdminStates } from './merged-admin-states.js';
 import { MergedAppMetadata } from './merged-app-metadata.js';
@@ -31,6 +32,7 @@ export type MergedSpec = Branded<'MergedSpec', {
     readonly adminPages: MergedAdminPages;
     readonly expressions: MergedExpressions;
     readonly adminExpressions: MergedExpressions;
+    readonly actions: MergedActions;
     readonly invariants: MergedInvariants;
     readonly adminInvariants: MergedInvariants;
     readonly relations: MergedRelations;

package/dist/application-spec/parse-application-files/merge/merged-spec.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{classifySpecFile as r}from"./classified-spec-file.js";import{MergedAdminComponents as m}from"./merged-admin-components.js";import{MergedAdminExpressions as o}from"./merged-admin-expressions.js";import{MergedAdminInvariants as s}from"./merged-admin-invariants.js";import{MergedAdminModel as t}from"./merged-admin-model.js";import{MergedAdminPages as d}from"./merged-admin-pages.js";import{MergedAdminPresets as i}from"./merged-admin-presets.js";import{MergedAdminRelations as p}from"./merged-admin-relations.js";import{MergedAdminStates as a}from"./merged-admin-states.js";import{MergedAppMetadata as n}from"./merged-app-metadata.js";import{MergedAssistant as g}from"./merged-assistant.js";import{MergedBudgets as f}from"./merged-budgets.js";import{MergedChunks as j}from"./merged-chunks.js";import{MergedComponents as l}from"./merged-components.js";import{MergedConfiguratorStates as c}from"./merged-configurator-states.js";import{MergedDataSchemas as M}from"./merged-data-schemas.js";import{MergedDataSpec as S}from"./merged-data-spec.js";import{MergedDefaults as u}from"./merged-defaults.js";import{MergedExpressions as h}from"./merged-expressions.js";import{MergedInfra as A}from"./merged-infra.js";import{MergedInvariants as x}from"./merged-invariants.js";import{MergedModel as k}from"./merged-model.js";import{MergedPresets as v}from"./merged-presets.js";import{MergedRelations as C}from"./merged-relations.js";import{MergedTheme as b}from"./merged-theme.js";import{MergedTransformers as q}from"./merged-transformers.js";import{MergedUi as w}from"./merged-ui.js";export const MergedSpec=(y,z)=>{let B=y.map(e=>r(e)),D=B.filter(e=>!e.isAdmin),E=B.filter(e=>e.isAdmin),F=z.startSpan("MergedModel","MergedSpec","merged-model.ts"),G=k(D,z);F();let H=z.startSpan("MergedAdminModel","MergedSpec","merged-admin-model.ts"),I=t(E,z);H();let J=z.startSpan("MergedComponents","MergedSpec","merged-components.ts"),K=l(D,z);J();let L=z.startSpan("MergedAdminComponents","MergedSpec","merged-admin-components.ts"),N=m(E,z);L();let O=v(D),P=i(E,z),Q=d(E,z),R=h(D,z),T=o(E,z),U=x(D,z),V=s(E,z),W=C(D,z),X=p(E,z),Y=u(D,z),Z=u(E,z),$=M(B,z),_=S(B,z),ee=c(D,z),er=a(E,z),em=b(B,z),eo=w(B,z),es=q(B,z),et=n(B,z),ed=A(B,z),ei=f(B,z);return e({model:G,adminModel:I,components:K,adminComponents:N,presets:O,adminPresets:P,adminPages:Q,expressions:R,adminExpressions:T,invariants:U,adminInvariants:V,relations:W,adminRelations:X,defaults:Y,adminDefaults:Z,dataSchemas:$,dataSpec:_,configuratorStates:ee,adminStates:er,theme:em,ui:eo,transformers:es,appMetadata:et,infra:ed,budgets:ei,chunks:j(B,z),assistant:g(B,z)})};
+import{Branded as e}from"@salsita-ai/common/utils";import{classifySpecFile as r}from"./classified-spec-file.js";import{MergedActions as m}from"./merged-actions.js";import{MergedAdminComponents as o}from"./merged-admin-components.js";import{MergedAdminExpressions as s}from"./merged-admin-expressions.js";import{MergedAdminInvariants as t}from"./merged-admin-invariants.js";import{MergedAdminModel as i}from"./merged-admin-model.js";import{MergedAdminPages as d}from"./merged-admin-pages.js";import{MergedAdminPresets as p}from"./merged-admin-presets.js";import{MergedAdminRelations as a}from"./merged-admin-relations.js";import{MergedAdminStates as n}from"./merged-admin-states.js";import{MergedAppMetadata as g}from"./merged-app-metadata.js";import{MergedAssistant as f}from"./merged-assistant.js";import{MergedBudgets as j}from"./merged-budgets.js";import{MergedChunks as l}from"./merged-chunks.js";import{MergedComponents as c}from"./merged-components.js";import{MergedConfiguratorStates as M}from"./merged-configurator-states.js";import{MergedDataSchemas as S}from"./merged-data-schemas.js";import{MergedDataSpec as u}from"./merged-data-spec.js";import{MergedDefaults as h}from"./merged-defaults.js";import{MergedExpressions as A}from"./merged-expressions.js";import{MergedInfra as x}from"./merged-infra.js";import{MergedInvariants as k}from"./merged-invariants.js";import{MergedModel as v}from"./merged-model.js";import{MergedPresets as C}from"./merged-presets.js";import{MergedRelations as b}from"./merged-relations.js";import{MergedTheme as q}from"./merged-theme.js";import{MergedTransformers as w}from"./merged-transformers.js";import{MergedUi as y}from"./merged-ui.js";export const MergedSpec=(z,B)=>{let D=z.map(e=>r(e)),E=D.filter(e=>!e.isAdmin),F=D.filter(e=>e.isAdmin),G=B.startSpan("MergedModel","MergedSpec","merged-model.ts"),H=v(E,B);G();let I=B.startSpan("MergedAdminModel","MergedSpec","merged-admin-model.ts"),J=i(F,B);I();let K=B.startSpan("MergedComponents","MergedSpec","merged-components.ts"),L=c(E,B);K();let N=B.startSpan("MergedAdminComponents","MergedSpec","merged-admin-components.ts"),O=o(F,B);N();let P=C(E),Q=p(F,B),R=d(F,B),T=A(E,B),U=s(F,B),V=m(D,B),W=k(E,B),X=t(F,B),Y=b(E,B),Z=a(F,B),$=h(E,B),_=h(F,B),ee=S(D,B),er=u(D,B),em=M(E,B),eo=n(F,B),es=q(D,B),et=y(D,B),ei=w(D,B),ed=g(D,B),ep=x(D,B),ea=j(D,B);return e({model:H,adminModel:J,components:L,adminComponents:O,presets:P,adminPresets:Q,adminPages:R,expressions:T,adminExpressions:U,actions:V,invariants:W,adminInvariants:X,relations:Y,adminRelations:Z,defaults:$,adminDefaults:_,dataSchemas:ee,dataSpec:er,configuratorStates:em,adminStates:eo,theme:es,ui:et,transformers:ei,appMetadata:ed,infra:ep,budgets:ea,chunks:l(D,B),assistant:f(D,B)})};

package/dist/application-spec/parse-application-files/raw-spec/index.d.ts

@@ -1,5 +1,6 @@
 export * from './raw-admin-pages.js';
 export * from './raw-acl.js';
+export * from './raw-actions.js';
 export * from './raw-assistant.js';
 export * from './raw-budgets.js';
 export * from './raw-chunks.js';

package/dist/application-spec/parse-application-files/raw-spec/index.js

@@ -1 +1 @@
-export*from"./raw-admin-pages.js";export*from"./raw-acl.js";export*from"./raw-assistant.js";export*from"./raw-budgets.js";export*from"./raw-chunks.js";export*from"./raw-components.js";export*from"./raw-constants.js";export*from"./raw-data.js";export*from"./raw-defaults.js";export*from"./raw-env.js";export*from"./raw-expressions.js";export*from"./raw-invariants.js";export*from"./raw-model.js";export*from"./raw-mock-templates.js";export*from"./raw-presets.js";export*from"./raw-relations.js";export*from"./raw-resources.js";export*from"./raw-spec-file.js";export*from"./raw-states.js";export*from"./raw-transformers.js";export*from"./parse-raw-spec.js";
+export*from"./raw-admin-pages.js";export*from"./raw-acl.js";export*from"./raw-actions.js";export*from"./raw-assistant.js";export*from"./raw-budgets.js";export*from"./raw-chunks.js";export*from"./raw-components.js";export*from"./raw-constants.js";export*from"./raw-data.js";export*from"./raw-defaults.js";export*from"./raw-env.js";export*from"./raw-expressions.js";export*from"./raw-invariants.js";export*from"./raw-model.js";export*from"./raw-mock-templates.js";export*from"./raw-presets.js";export*from"./raw-relations.js";export*from"./raw-resources.js";export*from"./raw-spec-file.js";export*from"./raw-states.js";export*from"./raw-transformers.js";export*from"./parse-raw-spec.js";

package/dist/application-spec/parse-application-files/raw-spec/raw-actions.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { type EnhancedJsonSchemaType } from '../../core/enhanced-json-schema.js';
+/**
+ * One action declared under the top-level `actions:` block: a domain operation the project
+ * implements in `src/actions/` and the application runs through the action system. `params` and
+ * `result` are maps of named enhanced JSON schemas; a `phx:DomainEntityId` param with `references`
+ * is typed by the referenced entity type or alias, and a `phx:$DomainEntity` result member with
+ * `references` is typed as the enhanced entity. The `description` of the action and of each param
+ * and result member documents it in the generated types; whoever exposes the action can reuse it.
+ */
+export interface RawActionEntry {
+    readonly description?: string;
+    readonly params: Readonly<Record<string, EnhancedJsonSchemaType>>;
+    readonly result: Readonly<Record<string, EnhancedJsonSchemaType>>;
+}
+/** Record of all action entries keyed by action name, produced by `rawSpecFileSchema` for the `actions:` block. */
+export type RawActions = Readonly<Record<string, RawActionEntry>>;
+export declare const rawActionsSchema: z.ZodType<RawActions, z.ZodTypeDef, unknown>;

package/dist/application-spec/parse-application-files/raw-spec/raw-actions.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{enhancedJsonSchema as r}from"../../core/enhanced-json-schema.js";let a=r=>e.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/,`is not a valid ${r} name: use letters, digits and underscores, starting with a letter, e.g. "partId"`),t=e.object({description:e.string().optional(),params:e.record(a("parameter"),r,{required_error:"is required: declare the parameters of the action as a map of named schemas, empty when it takes none",invalid_type_error:"must be a map of parameter names to JSON schemas"}),result:e.record(a("result member"),r,{required_error:"is required: declare the result of the action as a map of named schemas",invalid_type_error:"must be a map of result member names to JSON schemas"})}).strict();export const rawActionsSchema=e.record(e.string(),t).readonly();

package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.d.ts

@@ -68,6 +68,16 @@ export interface RawAssistantRecipes {
     readonly hints?: readonly AssistantHint[];
     readonly groups: Readonly<Record<string, RawAssistantRecipeGroup | null>>;
 }
+/**
+ * One entry of the assistant `actions` map, keyed by the name of an action declared under the
+ * top-level `actions` block: it exposes the action as a `Mutation` field named `as` (the action name
+ * by default) with `description` (the action's own by default). An empty entry (`movePartBy:` in
+ * YAML) exposes the action with its defaults.
+ */
+export interface RawAssistantAction {
+    readonly description?: string;
+    readonly as?: string;
+}
 /**
  * Experimental assistant manifest authored under the `assistant` root key. `entities` whitelists the
  * stored fields the generated GraphQL schema exposes, keyed by entity type or alias name and then by
@@ -77,8 +87,9 @@ export interface RawAssistantRecipes {
  * have to be exposed in `entities`. `childRecipes` names, per
  * entity type or alias, the `childEntityRecipes` groups whose recipes the agent may list and add
  * with `addChild`. `replaceRecipes` names, per entity type or alias, the `replaceEntityRecipes`
- * groups whose recipes the agent may list and replace the entity by with `replaceEntity`. Nothing is
- * exposed without an entry.
+ * groups whose recipes the agent may list and replace the entity by with `replaceEntity`. `actions`
+ * names the declared actions the agent may run as custom mutations. Nothing is exposed without an
+ * entry.
  *
  * `ai` and `instructions` are for the server only: the provider, model tier and reasoning level the
  * deployment's assistant runs with, and the integrator's own guidance for it, appended to the system
@@ -90,6 +101,7 @@ export interface RawAssistant {
     readonly writable?: Readonly<Record<string, Readonly<Record<string, RawAssistantWritableField | null>>>>;
     readonly childRecipes?: Readonly<Record<string, RawAssistantRecipes>>;
     readonly replaceRecipes?: Readonly<Record<string, RawAssistantRecipes>>;
+    readonly actions?: Readonly<Record<string, RawAssistantAction | null>>;
     readonly instructions?: string;
     readonly ai: AssistantAiSettings;
 }

package/dist/application-spec/parse-application-files/raw-spec/raw-assistant.js

@@ -1 +1 @@
-import{z as t}from"zod";import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as o,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";export const ASSISTANT_OPTION_COMPONENT_TYPES=["materialSwatch","attributeSelection","distanceDimensionSelect"];export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];let n=t.string().regex(/^(?!__)[_A-Za-z][_0-9A-Za-z]*$/,'must be a GraphQL name: letters, digits and "_", not starting with a digit or "__"'),r=e=>t.enum(e,{errorMap:()=>({message:`must be one of: ${e.join(", ")}`})}),s=t.object({description:t.string().optional(),as:n.optional()}).strict(),a=t.array(r(ASSISTANT_HINTS)),c=t.object({options:t.object({componentType:r(ASSISTANT_OPTION_COMPONENT_TYPES),instanceName:t.string().min(1,"must not be empty; name the component instance that holds the choices"),as:n.optional(),validate:t.boolean().optional(),allowDryRuns:t.boolean().optional(),hints:a.optional()}).strict().optional()}).strict(),l=t.object({as:t.string().trim().min(1,"must not be empty; remove the key to use the instance name").optional(),description:t.string().optional(),allowDryRuns:t.boolean().optional()}).strict(),p=e=>t.object({hints:a.optional(),groups:t.record(t.string(),l.nullable(),{required_error:`is required: the recipe groups of the type go under "groups", keyed by the instance name of a "${e}" component`})}).strict(),m=`is required: declare provider (${e.join(", ")}), model (${o.join(", ")}) and reasoning (${i.join(", ")})`,d=t.object({provider:r(e),model:r(o),reasoning:r(i)},{required_error:m,invalid_type_error:m}).strict();export const rawAssistantSchema=t.object({entities:t.record(t.string(),t.record(t.string(),s.nullable())).optional(),deletable:t.record(t.string(),t.object({}).strict().nullable()).optional(),writable:t.record(t.string(),t.record(t.string(),c.nullable())).optional(),childRecipes:t.record(t.string(),p("childEntityRecipes")).optional(),replaceRecipes:t.record(t.string(),p("replaceEntityRecipes")).optional(),instructions:t.string().trim().min(1,"must not be empty; remove the key when there are no instructions").optional(),ai:d}).strict();
+import{z as t}from"zod";import{ASSISTANT_AI_PROVIDERS as e,ASSISTANT_MODEL_TIERS as o,ASSISTANT_REASONING_LEVELS as i}from"@salsita-ai/contracts/assistant";export const ASSISTANT_OPTION_COMPONENT_TYPES=["materialSwatch","attributeSelection","distanceDimensionSelect"];export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];let n=t.string().regex(/^(?!__)[_A-Za-z][_0-9A-Za-z]*$/,'must be a GraphQL name: letters, digits and "_", not starting with a digit or "__"'),r=e=>t.enum(e,{errorMap:()=>({message:`must be one of: ${e.join(", ")}`})}),s=t.object({description:t.string().optional(),as:n.optional()}).strict(),a=t.array(r(ASSISTANT_HINTS)),c=t.object({options:t.object({componentType:r(ASSISTANT_OPTION_COMPONENT_TYPES),instanceName:t.string().min(1,"must not be empty; name the component instance that holds the choices"),as:n.optional(),validate:t.boolean().optional(),allowDryRuns:t.boolean().optional(),hints:a.optional()}).strict().optional()}).strict(),l=t.object({as:t.string().trim().min(1,"must not be empty; remove the key to use the instance name").optional(),description:t.string().optional(),allowDryRuns:t.boolean().optional()}).strict(),p=e=>t.object({hints:a.optional(),groups:t.record(t.string(),l.nullable(),{required_error:`is required: the recipe groups of the type go under "groups", keyed by the instance name of a "${e}" component`})}).strict(),d=t.object({description:t.string().optional(),as:n.optional()}).strict(),m=`is required: declare provider (${e.join(", ")}), model (${o.join(", ")}) and reasoning (${i.join(", ")})`,g=t.object({provider:r(e),model:r(o),reasoning:r(i)},{required_error:m,invalid_type_error:m}).strict();export const rawAssistantSchema=t.object({entities:t.record(t.string(),t.record(t.string(),s.nullable())).optional(),deletable:t.record(t.string(),t.object({}).strict().nullable()).optional(),writable:t.record(t.string(),t.record(t.string(),c.nullable())).optional(),childRecipes:t.record(t.string(),p("childEntityRecipes")).optional(),replaceRecipes:t.record(t.string(),p("replaceEntityRecipes")).optional(),actions:t.record(t.string(),d.nullable()).optional(),instructions:t.string().trim().min(1,"must not be empty; remove the key when there are no instructions").optional(),ai:g}).strict();

package/dist/application-spec/parse-application-files/raw-spec/raw-spec-file.d.ts

@@ -2,6 +2,7 @@ import { Branded } from '@salsita-ai/common/utils';
 import { type EnhancedJsonObjectSchemaType, type ParseContext } from '../../core/index.js';
 import type { ParsedYamlFile } from './parse-yaml-spec-file.js';
 import { type RawAcl } from './raw-acl.js';
+import { type RawActions } from './raw-actions.js';
 import { type RawAdminPages } from './raw-admin-pages.js';
 import { type RawAssistant } from './raw-assistant.js';
 import { type RawBudgets } from './raw-budgets.js';
@@ -24,6 +25,7 @@ export interface RawSpecContent {
     readonly presets?: RawPresets;
     readonly $data?: RawDataSpec;
     readonly expressions?: RawExpressions;
+    readonly actions?: RawActions;
     readonly invariants?: RawInvariants;
     readonly relations?: RawRelations;
     readonly defaults?: RawDefaults;

package/dist/application-spec/parse-application-files/raw-spec/raw-spec-file.js

@@ -1 +1 @@
-import{z as o}from"zod";import{Branded as a}from"@salsita-ai/common/utils";import{enhancedJsonObjectSchema as t,validateNoLegacyCodeRef as e}from"../../core/index.js";import{DiagnosticCode as n,diagnosticMessages as r}from"../../errors/index.js";import{rawAclSchema as i}from"./raw-acl.js";import{rawAdminPagesSchema as s}from"./raw-admin-pages.js";import{rawAssistantSchema as l}from"./raw-assistant.js";import{rawBudgetsSchema as p}from"./raw-budgets.js";import{rawChunksSchema as m}from"./raw-chunks.js";import{rawComponentsSchema as c}from"./raw-components.js";import{rawConstantsSchema as f}from"./raw-constants.js";import{rawDataSpecSchema as d}from"./raw-data.js";import{rawDefaultsSchema as u}from"./raw-defaults.js";import{rawEnvSchema as j}from"./raw-env.js";import{rawExpressionsSchema as w}from"./raw-expressions.js";import{rawInvariantsSchema as b}from"./raw-invariants.js";import{rawModelSchema as g}from"./raw-model.js";import{rawPresetsSchema as S}from"./raw-presets.js";import{rawRelationsSchema as D}from"./raw-relations.js";import{rawResourcesConfigSchema as h,rawResourcesSchema as v}from"./raw-resources.js";import{rawStateValuesSchema as O}from"./raw-states.js";import{rawTransformersSchema as E}from"./raw-transformers.js";export const DATA_SCHEMA_KEYS=["publishedData","sessionData","frontendData","backendData","finalizeData","prefetchedFinalizeData","finalizeResult","callbackData"];let R=o.object({$admin:o.boolean().optional(),model:g.optional(),components:c.optional(),presets:S.optional(),$data:d.optional(),expressions:w.optional(),invariants:b.optional(),constants:f.optional(),relations:D.optional(),defaults:u.optional(),publishedData:t.optional(),sessionData:t.optional(),frontendData:t.optional(),backendData:t.optional(),finalizeData:t.optional(),prefetchedFinalizeData:t.optional(),finalizeResult:t.optional(),callbackData:t.optional(),navigationStates:O.optional(),viewStates:O.optional(),toolStates:O.optional(),exportStates:O.optional(),themePreset:o.string().optional(),themeOptions:o.record(o.unknown()).optional(),preview:o.enum(["always","never","auto","hide"]).optional(),alwaysExpand:o.boolean().optional(),availableLocales:o.array(o.string()).optional(),textLanguages:o.array(o.string()).optional(),transformers:E.optional(),project:o.string().regex(/^[a-z0-9-]{3,}$/,"must be a project slug (lowercase letters, digits and dashes, at least 3) or `default`").optional(),applicationVersion:o.string().optional(),workspace:o.boolean().optional(),webComponentTag:o.string().optional(),pageTitle:o.string().optional(),useAuthHook:o.boolean().optional(),useClerk:o.boolean().optional(),enableAdminRelease:o.boolean().optional(),jsonSchemaValidator:o.enum(["ajv","csp-compatible"]).optional(),gltfDecoder:o.enum(["js","wasm"]).optional(),appLoader:o.enum(["legacy","universal"]).optional(),collectFinalizeData:o.boolean().optional(),env:j.optional(),acl:i.optional(),resources:v.optional(),resourcesConfig:h.optional(),budgets:p.optional(),chunks:m.optional(),assistant:l.optional(),$adminPages:s.optional()}).strict();export const parseRawSpecFile=(o,t)=>{e(o.content,t);let i=R.safeParse(o.content);if(!i.success){for(let o of i.error.issues)t.error(n.SCHEMA_PARSE_ERROR,r.SCHEMA_PARSE_ERROR(o.path.join("."),o.message));return}let{constants:s,...l}=i.data,p=((o,a)=>{let t=Object.fromEntries(Object.entries(o.expressions??{}).map(([o,a])=>[o,{...a}]));if(void 0===o.constants)return Object.keys(t).length>0?t:void 0;for(let[e,i]of Object.entries(o.constants))for(let[o,s]of(t[e]||(t[e]={}),Object.entries(i))){if(void 0!==t[e][o]){a.at("constants",e,o).error(n.CONSTANTS_EXPRESSION_CONFLICT,r[n.CONSTANTS_EXPRESSION_CONFLICT](e,o));continue}t[e][o]={kind:"value",constant:!0,value:s,schema:{}}}return Object.keys(t).length>0?t:void 0})(i.data,t);return a({name:o.name,content:{...l,expressions:p}})};
+import{z as o}from"zod";import{Branded as a}from"@salsita-ai/common/utils";import{enhancedJsonObjectSchema as t,validateNoLegacyCodeRef as e}from"../../core/index.js";import{DiagnosticCode as n,diagnosticMessages as i}from"../../errors/index.js";import{rawAclSchema as r}from"./raw-acl.js";import{rawActionsSchema as s}from"./raw-actions.js";import{rawAdminPagesSchema as l}from"./raw-admin-pages.js";import{rawAssistantSchema as p}from"./raw-assistant.js";import{rawBudgetsSchema as m}from"./raw-budgets.js";import{rawChunksSchema as c}from"./raw-chunks.js";import{rawComponentsSchema as f}from"./raw-components.js";import{rawConstantsSchema as d}from"./raw-constants.js";import{rawDataSpecSchema as u}from"./raw-data.js";import{rawDefaultsSchema as j}from"./raw-defaults.js";import{rawEnvSchema as w}from"./raw-env.js";import{rawExpressionsSchema as b}from"./raw-expressions.js";import{rawInvariantsSchema as g}from"./raw-invariants.js";import{rawModelSchema as S}from"./raw-model.js";import{rawPresetsSchema as D}from"./raw-presets.js";import{rawRelationsSchema as h}from"./raw-relations.js";import{rawResourcesConfigSchema as v,rawResourcesSchema as O}from"./raw-resources.js";import{rawStateValuesSchema as E}from"./raw-states.js";import{rawTransformersSchema as R}from"./raw-transformers.js";export const DATA_SCHEMA_KEYS=["publishedData","sessionData","frontendData","backendData","finalizeData","prefetchedFinalizeData","finalizeResult","callbackData"];let k=o.object({$admin:o.boolean().optional(),model:S.optional(),components:f.optional(),presets:D.optional(),$data:u.optional(),expressions:b.optional(),actions:s.optional(),invariants:g.optional(),constants:d.optional(),relations:h.optional(),defaults:j.optional(),publishedData:t.optional(),sessionData:t.optional(),frontendData:t.optional(),backendData:t.optional(),finalizeData:t.optional(),prefetchedFinalizeData:t.optional(),finalizeResult:t.optional(),callbackData:t.optional(),navigationStates:E.optional(),viewStates:E.optional(),toolStates:E.optional(),exportStates:E.optional(),themePreset:o.string().optional(),themeOptions:o.record(o.unknown()).optional(),preview:o.enum(["always","never","auto","hide"]).optional(),alwaysExpand:o.boolean().optional(),availableLocales:o.array(o.string()).optional(),textLanguages:o.array(o.string()).optional(),transformers:R.optional(),project:o.string().regex(/^[a-z0-9-]{3,}$/,"must be a project slug (lowercase letters, digits and dashes, at least 3) or `default`").optional(),applicationVersion:o.string().optional(),workspace:o.boolean().optional(),webComponentTag:o.string().optional(),pageTitle:o.string().optional(),useAuthHook:o.boolean().optional(),useClerk:o.boolean().optional(),enableAdminRelease:o.boolean().optional(),jsonSchemaValidator:o.enum(["ajv","csp-compatible"]).optional(),gltfDecoder:o.enum(["js","wasm"]).optional(),appLoader:o.enum(["legacy","universal"]).optional(),collectFinalizeData:o.boolean().optional(),env:w.optional(),acl:r.optional(),resources:O.optional(),resourcesConfig:v.optional(),budgets:m.optional(),chunks:c.optional(),assistant:p.optional(),$adminPages:l.optional()}).strict();export const parseRawSpecFile=(o,t)=>{e(o.content,t);let r=k.safeParse(o.content);if(!r.success){for(let o of r.error.issues)t.error(n.SCHEMA_PARSE_ERROR,i.SCHEMA_PARSE_ERROR(o.path.join("."),o.message));return}let{constants:s,...l}=r.data,p=((o,a)=>{let t=Object.fromEntries(Object.entries(o.expressions??{}).map(([o,a])=>[o,{...a}]));if(void 0===o.constants)return Object.keys(t).length>0?t:void 0;for(let[e,r]of Object.entries(o.constants))for(let[o,s]of(t[e]||(t[e]={}),Object.entries(r))){if(void 0!==t[e][o]){a.at("constants",e,o).error(n.CONSTANTS_EXPRESSION_CONFLICT,i[n.CONSTANTS_EXPRESSION_CONFLICT](e,o));continue}t[e][o]={kind:"value",constant:!0,value:s,schema:{}}}return Object.keys(t).length>0?t:void 0})(r.data,t);return a({name:o.name,content:{...l,expressions:p}})};

package/dist/application-spec/parse-application-files/resolve/resolve-import-modules.js

@@ -1 +1 @@
-import{mapSchema as e,resolveProjectFileImport as t,resolveProjectPath as r}from"../../core/index.js";import{DiagnosticCode as o,diagnosticMessages as s}from"../../errors/index.js";import{DATA_SCHEMA_KEYS as m}from"../raw-spec/index.js";let n=(m,n,p,i)=>e(m,(e,m)=>e.import?{...e,import:e.import.map((e,a)=>{if(!e.module.startsWith("."))return e;let c=r(n,e.module),O=i.at(...m,"import",String(a),"module");c.escapedProjectRoot?O.warning(o.IMPORT_MODULE_OUTSIDE_PROJECT,s[o.IMPORT_MODULE_OUTSIDE_PROJECT](e.module,c.path)):t(n,e.module,p)||O.error(o.IMPORT_MODULE_NOT_FOUND,s[o.IMPORT_MODULE_NOT_FOUND](e.module,c.path));let d=c.path.startsWith(".")?c.path:`./${c.path}`;return{...e,module:d}})}:e);export const resolveImportModules=(e,t,r)=>{let o=e.content.model?Object.fromEntries(Object.entries(e.content.model).map(([o,s])=>[o,{...s,...s.commonTypes?{commonTypes:Object.fromEntries(Object.entries(s.commonTypes).map(([s,m])=>[s,n(m,e.name,t,r.at("model",o,"commonTypes",s))]))}:{},...s.shapes?{shapes:Object.fromEntries(Object.entries(s.shapes).map(([s,m])=>[s,Object.fromEntries(Object.entries(m).map(([m,p])=>[m,n(p,e.name,t,r.at("model",o,"shapes",s,m))]))]))}:{}}])):void 0,s=e.content.expressions?Object.fromEntries(Object.entries(e.content.expressions).map(([o,s])=>[o,Object.fromEntries(Object.entries(s).map(([s,m])=>[s,{...m,schema:n(m.schema,e.name,t,r.at("expressions",o,s))}]))])):void 0,p=Object.fromEntries(m.flatMap(o=>{let s,m=e.content[o];return m?[[o,{...s=n(m,e.name,t,r.at(o)),type:"object",properties:s.properties??{},required:s.required??[],additionalProperties:!1}]]:[]}));return{...e.content,...o?{model:o}:{},...s?{expressions:s}:{},...p}};
+import{mapSchema as e,resolveProjectFileImport as t,resolveProjectPath as r}from"../../core/index.js";import{DiagnosticCode as o,diagnosticMessages as s}from"../../errors/index.js";import{DATA_SCHEMA_KEYS as n}from"../raw-spec/index.js";let m=(n,m,a,i)=>e(n,(e,n)=>e.import?{...e,import:e.import.map((e,p)=>{if(!e.module.startsWith("."))return e;let c=r(m,e.module),O=i.at(...n,"import",String(p),"module");c.escapedProjectRoot?O.warning(o.IMPORT_MODULE_OUTSIDE_PROJECT,s[o.IMPORT_MODULE_OUTSIDE_PROJECT](e.module,c.path)):t(m,e.module,a)||O.error(o.IMPORT_MODULE_NOT_FOUND,s[o.IMPORT_MODULE_NOT_FOUND](e.module,c.path));let l=c.path.startsWith(".")?c.path:`./${c.path}`;return{...e,module:l}})}:e);export const resolveImportModules=(e,t,r)=>{let o=e.content.model?Object.fromEntries(Object.entries(e.content.model).map(([o,s])=>[o,{...s,...s.commonTypes?{commonTypes:Object.fromEntries(Object.entries(s.commonTypes).map(([s,n])=>[s,m(n,e.name,t,r.at("model",o,"commonTypes",s))]))}:{},...s.shapes?{shapes:Object.fromEntries(Object.entries(s.shapes).map(([s,n])=>[s,Object.fromEntries(Object.entries(n).map(([n,a])=>[n,m(a,e.name,t,r.at("model",o,"shapes",s,n))]))]))}:{}}])):void 0,s=e.content.expressions?Object.fromEntries(Object.entries(e.content.expressions).map(([o,s])=>[o,Object.fromEntries(Object.entries(s).map(([s,n])=>[s,{...n,schema:m(n.schema,e.name,t,r.at("expressions",o,s))}]))])):void 0,a=e.content.actions?Object.fromEntries(Object.entries(e.content.actions).map(([o,s])=>{let n=(s,n)=>Object.fromEntries(Object.entries(s).map(([s,a])=>[s,m(a,e.name,t,r.at("actions",o,n,s))]));return[o,{...s,params:n(s.params,"params"),result:n(s.result,"result")}]})):void 0,i=Object.fromEntries(n.flatMap(o=>{let s,n=e.content[o];return n?[[o,{...s=m(n,e.name,t,r.at(o)),type:"object",properties:s.properties??{},required:s.required??[],additionalProperties:!1}]]:[]}));return{...e.content,...o?{model:o}:{},...s?{expressions:s}:{},...a?{actions:a}:{},...i}};

package/dist/application-spec/parse-application-files/spec/application/application-spec.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{AppMetadata as s,BundleSizeBudgets as a,DataSpec as t,Infra as n}from"../sections/index.js";import{AdminSpec as r}from"./admin-spec/index.js";import{ConfiguratorSpec as o}from"./configurator-spec/index.js";export const ApplicationSpec=(i,l)=>{let{merged:m,migrationFiles:p,adminMigrationFiles:d,transformerFiles:c,phxDefinitions:u,evalExpressionParser:w}=i,f=s(m.appMetadata,l);if(!f)return;let S=t({mergedDataSpec:m.dataSpec,mergedChunks:m.chunks},l);if(!S||l.hasErrors)return;let g=l.startSpan("ConfiguratorSpec","ApplicationSpec"),h=o({rawModel:m.model,rawPresets:m.presets,rawExpressions:m.expressions,rawInvariants:m.invariants,rawRelations:m.relations,rawDefaults:m.defaults,dataSchemas:m.dataSchemas,dataSpec:S,appMetadata:f,rawTheme:m.theme,rawUi:m.ui,rawTransformers:m.transformers,rawAssistant:m.assistant,migrationFiles:p,transformerFiles:c,rawComponents:m.components,rawStates:m.configuratorStates,phxDefinitions:u,evalExpressionParser:w,label:"model"},l);if(g(),!h)return;let M=l.startSpan("AdminSpec","ApplicationSpec"),x=r({rawModel:m.adminModel,rawPresets:m.adminPresets,rawExpressions:m.adminExpressions,rawInvariants:m.adminInvariants,rawRelations:m.adminRelations,rawDefaults:m.adminDefaults,migrationFiles:d,rawComponents:m.adminComponents,rawAdminPages:m.adminPages,rawStates:m.adminStates,dataSpec:S,phxDefinitions:u,evalExpressionParser:w,label:"adminModel",requireMigrationFiles:!0},l);if(M(),!x)return;let v=n(m.infra,l);if(!v)return;let y=a(m.budgets);return l.count("entityTypes",h.latestModel.entityTypes.length),l.count("aliases",h.latestModel.aliases.size),l.count("commonTypes",h.latestModel.commonTypes.size),l.count("shapes",h.latestModel.shapes.size),l.count("components",h.components.length),l.count("modelVersions",h.resolvedVersions.versionedModels.length),l.count("presets",h.presets.presets.length),e({configurator:h,admin:x,appMetadata:f,infra:v,budgets:y,dataSpec:S})};
+import{Branded as e}from"@salsita-ai/common/utils";import{AppMetadata as s,BundleSizeBudgets as a,DataSpec as t,Infra as n}from"../sections/index.js";import{AdminSpec as r}from"./admin-spec/index.js";import{ConfiguratorSpec as o}from"./configurator-spec/index.js";export const ApplicationSpec=(i,l)=>{let{merged:m,migrationFiles:p,adminMigrationFiles:d,transformerFiles:c,phxDefinitions:u,evalExpressionParser:w}=i,f=s(m.appMetadata,l);if(!f)return;let S=t({mergedDataSpec:m.dataSpec,mergedChunks:m.chunks},l);if(!S||l.hasErrors)return;let g=l.startSpan("ConfiguratorSpec","ApplicationSpec"),h=o({rawModel:m.model,rawPresets:m.presets,rawExpressions:m.expressions,rawActions:m.actions,rawInvariants:m.invariants,rawRelations:m.relations,rawDefaults:m.defaults,dataSchemas:m.dataSchemas,dataSpec:S,appMetadata:f,rawTheme:m.theme,rawUi:m.ui,rawTransformers:m.transformers,rawAssistant:m.assistant,migrationFiles:p,transformerFiles:c,rawComponents:m.components,rawStates:m.configuratorStates,phxDefinitions:u,evalExpressionParser:w,label:"model"},l);if(g(),!h)return;let M=l.startSpan("AdminSpec","ApplicationSpec"),x=r({rawModel:m.adminModel,rawPresets:m.adminPresets,rawExpressions:m.adminExpressions,rawInvariants:m.adminInvariants,rawRelations:m.adminRelations,rawDefaults:m.adminDefaults,migrationFiles:d,rawComponents:m.adminComponents,rawAdminPages:m.adminPages,rawStates:m.adminStates,dataSpec:S,phxDefinitions:u,evalExpressionParser:w,label:"adminModel",requireMigrationFiles:!0},l);if(M(),!x)return;let A=n(m.infra,l);if(!A)return;let v=a(m.budgets);return l.count("entityTypes",h.latestModel.entityTypes.length),l.count("aliases",h.latestModel.aliases.size),l.count("commonTypes",h.latestModel.commonTypes.size),l.count("shapes",h.latestModel.shapes.size),l.count("components",h.components.length),l.count("modelVersions",h.resolvedVersions.versionedModels.length),l.count("presets",h.presets.presets.length),e({configurator:h,admin:x,appMetadata:f,infra:A,budgets:v,dataSpec:S})};

package/dist/application-spec/parse-application-files/spec/application/configurator-spec/configurator-spec.d.ts

@@ -1,12 +1,12 @@
 import { Branded } from '@salsita-ai/common/utils';
 import { type EvalExpressionParser, type ParseContext, type PhoenixDefinitions } from '../../../../core/index.js';
 import type { CategorizedFile } from '../../../categorize/index.js';
-import type { MergedAssistant, MergedComponents, MergedConfiguratorStates, MergedDataSchemas, MergedDefaults, MergedExpressions, MergedInvariants, MergedModel, MergedPresets, MergedRelations, MergedTheme, MergedTransformers, MergedUi } from '../../../merge/index.js';
+import type { MergedActions, MergedAssistant, MergedComponents, MergedConfiguratorStates, MergedDataSchemas, MergedDefaults, MergedExpressions, MergedInvariants, MergedModel, MergedPresets, MergedRelations, MergedTheme, MergedTransformers, MergedUi } from '../../../merge/index.js';
 import { Components } from '../../components/index.js';
 import { Expressions } from '../../expressions/index.js';
 import { Invariants } from '../../invariants/index.js';
 import { ConfigurationSchema, DataSchemas, Defaults, ModelVersion, Presets } from '../../model/index.js';
-import { type AppMetadata, AssistantServerSettings, AssistantSpec, type DataSpec, Theme, Transformers, Ui } from '../../sections/index.js';
+import { Actions, type AppMetadata, AssistantServerSettings, AssistantSpec, type DataSpec, Theme, Transformers, Ui } from '../../sections/index.js';
 import { ResolvedVersions } from '../resolved-versions.js';
 import { ConfiguratorStates } from './states.js';
 export type ConfiguratorSpec = Branded<'ConfiguratorSpec', {
@@ -17,6 +17,7 @@ export type ConfiguratorSpec = Branded<'ConfiguratorSpec', {
     readonly configurationSchema: ConfigurationSchema;
     readonly presets: Presets;
     readonly expressions: Expressions;
+    readonly actions: Actions;
     readonly invariants: Invariants;
     readonly dataSchemas: DataSchemas;
     readonly defaults: Defaults;
@@ -31,6 +32,7 @@ interface ConfiguratorSpecProps {
     readonly rawModel: MergedModel;
     readonly rawPresets: MergedPresets;
     readonly rawExpressions: MergedExpressions;
+    readonly rawActions: MergedActions;
     readonly rawInvariants: MergedInvariants;
     readonly rawRelations: MergedRelations;
     readonly rawDefaults: MergedDefaults;

package/dist/application-spec/parse-application-files/spec/application/configurator-spec/configurator-spec.js

@@ -1 +1 @@
-import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as s,diagnosticMessages as t}from"../../../../errors/index.js";import{Components as r,UserComponents as o}from"../../components/index.js";import{Expressions as i}from"../../expressions/index.js";import{Invariants as n}from"../../invariants/index.js";import{ConfigurationSchema as a,DataSchemas as m,Defaults as p,ModelVersion as l,Presets as d}from"../../model/index.js";import{Relations as f}from"../../relations/index.js";import{AssistantServerSettings as x,AssistantSpec as S,Theme as v,Transformers as c,Ui as j}from"../../sections/index.js";import{ResolvedVersions as u}from"../resolved-versions.js";import{ConfiguratorStates as g}from"./states.js";export const ConfiguratorSpec=(C,I)=>{let{rawModel:M,rawPresets:h,rawExpressions:y,rawInvariants:E,rawRelations:N,rawDefaults:T,dataSchemas:L,dataSpec:G,appMetadata:O,rawTheme:_,rawUi:b,rawTransformers:w,rawAssistant:A,migrationFiles:D,transformerFiles:V,rawComponents:k,phxDefinitions:K,evalExpressionParser:q,label:z}=C;if(0===Object.keys(M).length)return void I.at(z).error(s.MISSING_MODEL,t.MISSING_MODEL(z));M.latest||I.at(z).error(s.MISSING_LATEST,t.MISSING_LATEST(z));let B=new Map;for(let[e,s]of Object.entries(M)){let t=l(e,s,K,I.at(z,e));t&&B.set(t.versionKey,t)}if(I.hasErrors)return;let F=u(B,D,I);if(!F)return;let H=F.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!H)return;let J=F.latestVersion,P=a(H,J),Q=f(N,H,I),R=n({rawInvariants:E,rawExpressions:y,rawRelations:N,rawComponents:k},H,I),U=d(h,H,Q,I),W=o(k,{allNames:H.allNames,resolvedShapes:H.resolvedShapes,parsingContext:I}),X=p(T,H,I.at(z,"defaults")),Y=c(w,V,I),Z=i({rawExpressions:y,inferredExpressions:[...Q.expressions,...R.expressions,...W.expressions]},{latestModel:H,aliases:H.aliases,entityTypes:H.entityTypes,evalExpressionParser:q,parsingContext:I}),$=r({userComponents:W.components,generatedComponents:Q.components,invariantComponents:R.components},{aliases:H.aliases,parsingContext:I}),ee=m({merged:L,dataSpec:G,appMetadata:O,phxDefinitions:K,parsingContext:I}),es=g(C.rawStates,I.at("states"));if(void 0!==X&&void 0!==Z&&void 0!==$&&void 0!==ee)return e({latestModel:H,schemaVersion:J,dataSchemas:ee,resolvedVersions:F,components:$,configurationSchema:P,presets:U,expressions:Z,invariants:R,defaults:X,states:es,theme:v(_),ui:j(b),transformers:Y,assistant:S(A,{model:H,states:es,phxDefinitions:K,expressions:Z,components:$},I),assistantServerSettings:x(A)})};
+import{Branded as e}from"@salsita-ai/common/utils";import{DiagnosticCode as s,diagnosticMessages as t}from"../../../../errors/index.js";import{Components as o,UserComponents as r}from"../../components/index.js";import{Expressions as i}from"../../expressions/index.js";import{Invariants as n}from"../../invariants/index.js";import{ConfigurationSchema as a,DataSchemas as m,Defaults as p,ModelVersion as l,Presets as d}from"../../model/index.js";import{Relations as f}from"../../relations/index.js";import{Actions as x,AssistantServerSettings as S,AssistantSpec as v,Theme as c,Transformers as j,Ui as u}from"../../sections/index.js";import{ResolvedVersions as g}from"../resolved-versions.js";import{ConfiguratorStates as C}from"./states.js";export const ConfiguratorSpec=(I,M)=>{let{rawModel:h,rawPresets:y,rawExpressions:E,rawActions:N,rawInvariants:T,rawRelations:L,rawDefaults:G,dataSchemas:O,dataSpec:_,appMetadata:b,rawTheme:w,rawUi:A,rawTransformers:D,rawAssistant:V,migrationFiles:k,transformerFiles:K,rawComponents:q,phxDefinitions:z,evalExpressionParser:B,label:F}=I;if(0===Object.keys(h).length)return void M.at(F).error(s.MISSING_MODEL,t.MISSING_MODEL(F));h.latest||M.at(F).error(s.MISSING_LATEST,t.MISSING_LATEST(F));let H=new Map;for(let[e,s]of Object.entries(h)){let t=l(e,s,z,M.at(F,e));t&&H.set(t.versionKey,t)}if(M.hasErrors)return;let J=g(H,k,M);if(!J)return;let P=J.versionedModels.find(e=>e.isLatest)?.modelVersion;if(!P)return;let Q=J.latestVersion,R=a(P,Q),U=f(L,P,M),W=n({rawInvariants:T,rawExpressions:E,rawRelations:L,rawComponents:q},P,M),X=d(y,P,U,M),Y=r(q,{allNames:P.allNames,resolvedShapes:P.resolvedShapes,parsingContext:M}),Z=p(G,P,M.at(F,"defaults")),$=j(D,K,M),ee=i({rawExpressions:E,inferredExpressions:[...U.expressions,...W.expressions,...Y.expressions]},{latestModel:P,aliases:P.aliases,entityTypes:P.entityTypes,evalExpressionParser:B,parsingContext:M}),es=o({userComponents:Y.components,generatedComponents:U.components,invariantComponents:W.components},{aliases:P.aliases,parsingContext:M}),et=m({merged:O,dataSpec:_,appMetadata:b,phxDefinitions:z,parsingContext:M}),eo=C(I.rawStates,M.at("states")),er=x(N,{latestModel:P,phxDefinitions:z},M.at("actions"));if(void 0!==Z&&void 0!==ee&&void 0!==er&&void 0!==es&&void 0!==et)return e({latestModel:P,schemaVersion:Q,dataSchemas:et,resolvedVersions:J,components:es,configurationSchema:R,presets:X,expressions:ee,actions:er,invariants:W,defaults:Z,states:eo,theme:c(w),ui:u(A),transformers:$,assistant:v(V,{model:P,states:eo,phxDefinitions:z,expressions:ee,components:es,actions:er},M),assistantServerSettings:S(V)})};

package/dist/application-spec/parse-application-files/spec/common/index.d.ts

@@ -1 +1,2 @@
+export * from './schema-ref-resolver.js';
 export * from './validate-schema-refs.js';

package/dist/application-spec/parse-application-files/spec/common/index.js

@@ -1 +1 @@
-export*from"./validate-schema-refs.js";
+export*from"./schema-ref-resolver.js";export*from"./validate-schema-refs.js";