@solidxai/core 0.1.13-beta.6 → 0.1.13-beta.7

package/docs/workflow/workflow-solidx-model-field-spec.md

@@ -0,0 +1,284 @@
+# Workflow SolidX Model Field Specification
+
+This document translates the agreed workflow-management domain model into SolidX model and field definitions.
+
+It is intended as the final field-level design pass before using the SolidX model MCP tools.
+
+## SolidX Field Types
+
+The local `@solidxai/core` package defines these field types in `SolidFieldType`:
+
+- `int`
+- `bigint`
+- `decimal`
+- `shortText`
+- `longText`
+- `richText`
+- `json`
+- `boolean`
+- `date`
+- `datetime`
+- `time`
+- `relation`
+- `mediaSingle`
+- `mediaMultiple`
+- `email`
+- `password`
+- `selectionStatic`
+- `selectionDynamic`
+- `computed`
+- `uuid`
+
+Useful relation metadata:
+
+- `relationType`: `many-to-one`, `one-to-many`, `many-to-many`
+- `relationCascade`: `set null`, `restrict`, `cascade`
+
+## Modeling Philosophy
+
+- Workflow definitions store their canonical DSL in YAML text.
+- Workflow definitions are metadata-backed: manually created workflows should also be persisted back to the module metadata JSON so developers can commit and share them.
+- Workflow execution data is normalized enough to support monitoring, filtering, and debugging.
+- Workflow version history is not a separate model in v1.
+- `definitionVersion` and `definitionChecksum` live on both definition and execution records.
+- `WorkflowBlueprint` is intentionally deferred for now.
+
+## Model: `workflowDefinition`
+
+Purpose: stores the current reusable workflow definition.
+
+Suggested table name: `wm_workflow_definition`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `key` | `shortText` | Yes | Stable workflow key. Should be unique. |
+| `moduleMetadata` | `relation` | Yes | Many-to-one to SolidX `moduleMetadata`; identifies the owning module/package for metadata persistence. |
+| `displayName` | `shortText` | Yes | Human-facing name. |
+| `namespace` | `shortText` | No | Dot-path grouping, e.g. `ops.monitoring`. |
+| `description` | `longText` | No | Workflow description. |
+| `status` | `selectionStatic` | Yes | `draft`, `active`, `inactive`, `archived`. |
+| `definitionVersion` | `shortText` | No | Human-managed or seed-managed version string. |
+| `definitionChecksum` | `shortText` | No | Hash of canonical `definitionYaml`. |
+| `definitionYaml` | `longText` | Yes | Canonical workflow DSL YAML used for sharing, seeding, validation, and execution. |
+| `tags` | `json` | No | Array of tags. |
+
+Recommended indexes/search fields:
+
+- `key`
+- `moduleMetadata`
+- `displayName`
+- `namespace`
+- `status`
+- `definitionChecksum`
+
+Recommended user key:
+
+- `key`
+
+Metadata persistence notes:
+
+- `key` acts as the workflow user key and metadata identity.
+- A TypeORM subscriber or workflow persistence service should synchronize workflow definition changes back to the owning module metadata JSON.
+- Since UI-created workflows are also metadata-backed, separate `sourceType`, `seedSource`, `seedKey`, `seedVersion`, and `isSeeded` fields are not needed.
+
+## Model: `workflowExecution`
+
+Purpose: stores one run of a workflow definition.
+
+Suggested table name: `wm_workflow_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `executionIdentifier` | `computed` | Yes | System-generated readable execution id. Recommended provider: `SequenceNumComputedFieldProvider`. |
+| `workflowDefinition` | `relation` | Yes | Many-to-one to `workflowDefinition`. |
+| `workflowKey` | `shortText` | Yes | Snapshot of definition key for easier querying. |
+| `workflowDisplayName` | `shortText` | No | Snapshot of display name. |
+| `status` | `selectionStatic` | Yes | `created`, `running`, `success`, `failed`, `cancelled`. |
+| `triggerType` | `selectionStatic` | Yes | `manual`, `schedule`, `webhook`, `flow`, `polling`, `event`. |
+| `triggerExecution` | `relation` | No | Many-to-one to `workflowTriggerExecution`; nullable for manual runs. |
+| `startedAt` | `datetime` | No | Execution start time. |
+| `finishedAt` | `datetime` | No | Execution end time. |
+| `durationMs` | `bigint` | No | Runtime duration. |
+| `inputPayload` | `json` | No | Runtime inputs supplied to the execution. |
+| `outputPayload` | `json` | No | Flow-level outputs. |
+| `definitionVersion` | `shortText` | No | Version used by this execution. |
+| `definitionChecksum` | `shortText` | No | Checksum used by this execution. |
+| `definitionSnapshot` | `longText` | Yes | Exact workflow YAML used for this run. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+| `requestedByUserId` | `bigint` | No | User id or actor id if available. |
+
+Recommended indexes/search fields:
+
+- `executionIdentifier`
+- `workflowKey`
+- `status`
+- `triggerType`
+- `startedAt`
+- `finishedAt`
+- `definitionChecksum`
+
+Recommended computed field configuration:
+
+- `type`: `computed`
+- `computedFieldValueProvider`: `SequenceNumComputedFieldProvider`
+- `computedFieldValueProviderCtxt`: `{"sequenceName":"workflowExecution","mode":"counter"}`
+- `computedFieldValueType`: `string`
+- `computedFieldTriggerConfig`: after insert for `workflowExecution`
+
+Recommended model sequence:
+
+- `sequenceName`: `workflowExecution`
+- `prefix`: `WFE`
+- `separator`: `-`
+- `padding`: `8`
+- Example output: `WFE-00000001`
+
+## Model: `workflowStepExecution`
+
+Purpose: stores runtime state for one workflow node execution.
+
+Suggested table name: `wm_workflow_step_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `parentStepExecution` | `relation` | No | Self many-to-one for nested/control execution. |
+| `nodeId` | `shortText` | Yes | Node id from workflow YAML. |
+| `nodeName` | `shortText` | No | Snapshot of node name. |
+| `nodeKind` | `selectionStatic` | Yes | `task`, `control`, `subflow`. |
+| `nodeType` | `shortText` | Yes | e.g. `http.request`, `if`. |
+| `status` | `selectionStatic` | Yes | `pending`, `running`, `success`, `failed`, `skipped`. |
+| `attemptNumber` | `int` | Yes | Defaults to 1. |
+| `branchId` | `shortText` | No | For `parallel` branch context. |
+| `iterationIndex` | `int` | No | For `forEach` context. |
+| `startedAt` | `datetime` | No | Step start time. |
+| `finishedAt` | `datetime` | No | Step end time. |
+| `durationMs` | `bigint` | No | Step runtime duration. |
+| `inputContext` | `json` | No | Resolved node input context. |
+| `outputPayload` | `json` | No | Node outputs. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `nodeId`
+- `nodeType`
+- `status`
+- `startedAt`
+
+## Model: `workflowExecutionLog`
+
+Purpose: stores execution and step logs as queryable records.
+
+Suggested table name: `wm_workflow_execution_log`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `workflowStepExecution` | `relation` | No | Many-to-one to `workflowStepExecution`; nullable for execution-level logs. |
+| `level` | `selectionStatic` | Yes | `debug`, `info`, `warn`, `error`. |
+| `message` | `longText` | Yes | Log message. |
+| `metadata` | `json` | No | Structured log metadata. |
+| `loggedAt` | `datetime` | Yes | Timestamp of log event. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `workflowStepExecution`
+- `level`
+- `loggedAt`
+
+## Model: `workflowExecutionArtifact`
+
+Purpose: stores references to files or large artifacts produced during execution.
+
+Suggested table name: `wm_workflow_execution_artifact`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `workflowStepExecution` | `relation` | No | Many-to-one to `workflowStepExecution`. |
+| `artifactKey` | `shortText` | Yes | Stable artifact key within the execution. |
+| `displayName` | `shortText` | No | Human-facing name. |
+| `artifactType` | `selectionStatic` | Yes | `file`, `json`, `text`, `binary`, `uri`. |
+| `media` | `mediaSingle` | No | SolidX media attachment for stored file artifacts. |
+| `uri` | `longText` | No | External artifact URI if not stored in media. |
+| `contentType` | `shortText` | No | MIME type if known. |
+| `sizeBytes` | `bigint` | No | Artifact size. |
+| `metadata` | `json` | No | Structured artifact metadata. |
+| `createdAtRuntime` | `datetime` | No | Runtime artifact creation timestamp. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `workflowStepExecution`
+- `artifactKey`
+- `artifactType`
+
+## Model: `workflowTriggerExecution`
+
+Purpose: records trigger events that started or attempted to start workflow executions.
+
+Suggested table name: `wm_workflow_trigger_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowDefinition` | `relation` | Yes | Many-to-one to `workflowDefinition`. |
+| `triggerId` | `shortText` | Yes | Trigger id from workflow YAML. |
+| `triggerType` | `selectionStatic` | Yes | `schedule`, `webhook`, `flow`, `polling`, `event`. |
+| `status` | `selectionStatic` | Yes | `received`, `accepted`, `ignored`, `failed`. |
+| `firedAt` | `datetime` | Yes | Trigger fire time. |
+| `inputPayload` | `json` | No | Inputs supplied by trigger. |
+| `triggerPayload` | `json` | No | Raw trigger/event payload. |
+| `workflowExecution` | `relation` | No | Many-to-one to `workflowExecution`; nullable if ignored/failed before execution creation. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+
+Recommended indexes/search fields:
+
+- `workflowDefinition`
+- `triggerId`
+- `triggerType`
+- `status`
+- `firedAt`
+
+## Deferred Model: `workflowBlueprint`
+
+`WorkflowBlueprint` is intentionally ignored for now.
+
+When reintroduced, it should likely include:
+
+- `key`
+- `displayName`
+- `description`
+- `tags`
+- `definitionYaml`
+- `source`
+- `sourceVersion`
+
+## Relation Summary
+
+- `workflowDefinition` has many `workflowExecution`
+- `workflowDefinition` has many `workflowTriggerExecution`
+- `moduleMetadata` has many `workflowDefinition`
+- `workflowExecution` has many `workflowStepExecution`
+- `workflowExecution` has many `workflowExecutionLog`
+- `workflowExecution` has many `workflowExecutionArtifact`
+- `workflowTriggerExecution` may link to one created `workflowExecution`
+- `workflowStepExecution` may have many child `workflowStepExecution` records via `parentStepExecution`
+- `workflowStepExecution` has many `workflowExecutionLog`
+- `workflowStepExecution` has many `workflowExecutionArtifact`
+
+## MCP Modeling Readiness Checklist
+
+Before calling the SolidX model MCP tools, confirm:
+
+- Use `workflow-builder` as the module key.
+- Use the six active models above.
+- Use `longText` for `definitionYaml` and `definitionSnapshot`; parse them as YAML in the workflow services to keep the workflow engine DB agnostic.
+- Use `selectionStatic` for status/type enum fields.
+- Use `relation` fields for cross-model links.
+- Add a many-to-one relation from `workflowDefinition` to SolidX `moduleMetadata`.
+- Keep `WorkflowBlueprint` deferred.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidxai/core",
-  "version": "0.1.13-beta.6",
+  "version": "0.1.13-beta.7",
   "description": "This module is a NestJS module containing all the required core providers required by a Solid application",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/seeders/seed-data/solid-core-metadata.json

@@ -7850,6 +7850,8 @@
         "FieldMetadataController.getSelectionDynamicValues",
         "FieldMetadataController.getSelectionDynamicValue",
         "FieldMetadataController.findFieldDefaultMetaData",
+        "MediaController.create",
+        "MediaController.upload",
         "MediaController.findMany",
         "MediaController.findOne",
         "MediaController.download",
@@ -8090,6 +8092,19 @@
       "moduleUserKey": "solid-core",
       "modelUserKey": "media"
     },
+    {
+      "displayName": "Media Upload Action",
+      "name": "media-upload-action",
+      "type": "custom",
+      "domain": "",
+      "context": "",
+      "customComponent": "/admin/core/solid-core/media/upload",
+      "customIsModal": false,
+      "serverEndpoint": "",
+      "viewUserKey": "media-list-view",
+      "moduleUserKey": "solid-core",
+      "modelUserKey": "media"
+    },
     {
       "displayName": "Solid Media Storage Provider Model List Action",
       "name": "mediaStorageProviderMetadata-list-action",
@@ -11565,7 +11580,8 @@
             50
           ],
           "enableGlobalSearch": true,
-          "create": false,
+          "create": true,
+          "createAction": "media-upload-action",
           "edit": false,
           "delete": true,
           "allowedViews": [
@@ -11603,6 +11619,15 @@
               "sortable": false
             }
           },
+          {
+            "type": "field",
+            "attrs": {
+              "name": "relativeUri",
+              "viewWidget": "MediaRelativeUriListWidget",
+              "isSearchable": true,
+              "sortable": false
+            }
+          },
           {
             "type": "field",
             "attrs": {
@@ -11759,7 +11784,8 @@
                   {
                     "type": "field",
                     "attrs": {
-                      "name": "relativeUri"
+                      "name": "relativeUri",
+                      "viewWidget": "MediaRelativeUriFormViewWidget"
                     }
                   },
                   {

package/src/services/media.service.ts

@@ -1,4 +1,4 @@
-import { forwardRef, Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { BadRequestException, forwardRef, Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { ModuleRef } from "@nestjs/core";
 import { InjectEntityManager } from '@nestjs/typeorm';
 import { EntityManager, In } from 'typeorm';
@@ -16,11 +16,12 @@ import { BasicFilterDto } from 'src/dtos/basic-filters.dto';
 import { MediaStorageProviderType } from 'src/dtos/create-media-storage-provider-metadata.dto';
 import { Media } from 'src/entities/media.entity';
 import { MediaStorageProviderMetadata } from 'src/entities/media-storage-provider-metadata.entity';
+import { MediaFieldCrudManager, SolidMediaType } from 'src/helpers/field-crud-managers/MediaFieldCrudManager';
 import { FieldMetadataRepository } from 'src/repository/field-metadata.repository';
 import { MediaStorageProviderMetadataRepository } from 'src/repository/media-storage-provider-metadata.repository';
 import { MediaRepository } from 'src/repository/media.repository';
 import { ModelMetadataRepository } from 'src/repository/model-metadata.repository';
-import { buildDiskMediaPath, buildStoredMediaFileName, getEffectiveS3Region, resolveMediaIsPublic, } from 'src/services/media-storage.utils';
+import { buildDiskMediaPath, getEffectiveS3Region, resolveMediaIsPublic, } from 'src/services/media-storage.utils';
 import { getMediaStorageProvider } from "./mediaStorageProviders";
 
 @Injectable()
@@ -103,40 +104,25 @@ export class MediaService extends CRUDService<Media> {
       throw new NotFoundException('Media storage provider metadata not found');
     }
 
-    const savedMedias = [];
-    for (let i = 0; i < files.length; i++) {
-      const file = files[i];
-      const storageProvider = createDto.mediaStorageProviderMetadata as MediaStorageProviderMetadata;
-      const fileName = buildStoredMediaFileName(file);
+    createDto['fieldMetadata'].mediaStorageProvider = createDto['mediaStorageProviderMetadata'];
 
-      switch (storageProvider.type) {
-        case MediaStorageProviderType.Filesystem:
-          const fileStoragePath = buildDiskMediaPath(fileName, this.settingService, storageProvider);
-          await this.diskFileService.copy(file.path, fileStoragePath);
-          createDto['relativeUri'] = fileName;
-          break;
-        case MediaStorageProviderType.AwsS3:
-          const bucketName = storageProvider.bucketName;
-          const region = getEffectiveS3Region(this.configService, storageProvider.region);
-
-          // Read file from disk and upload to S3
-          const fileData = await this.diskFileService.read(file.path);
-          await this.s3FileService.write(`${bucketName}:${fileName}`, fileData, { contentType: file.mimetype, region });
+    const validator = new MediaFieldCrudManager({
+      type: createDto['fieldMetadata']?.type as SolidMediaType,
+      required: true,
+      fieldName: 'files',
+      mediaMaxSizeKb: createDto['fieldMetadata']?.mediaMaxSizeKb,
+      mediaTypes: createDto['fieldMetadata']?.mediaTypes || [],
+      isUpdate: false,
+    });
+    const validationErrors = validator.validate(createDto, files);
+    if (validationErrors.length > 0) {
+      throw new BadRequestException(validationErrors.map(error => error.error).join(', '));
+    }
 
-          createDto['relativeUri'] = fileName;
-          break;
-        default:
-          break;
-      }
-      // Delete temp file from disk
-      await this.diskFileService.delete(file.path);
+    const storageProviderType = createDto['mediaStorageProviderMetadata'].type as MediaStorageProviderType;
+    const storageProvider = await getMediaStorageProvider(this.moduleRef, storageProviderType);
 
-      delete createDto['isPublic'];
-      const media = this.repo.create(createDto as Partial<Media>) as Media;
-      const savedMedia = await this.repo.save(media);
-      savedMedias.push(savedMedia)
-    }
-    return savedMedias
+    return storageProvider.store(files, { id: Number(createDto['entityId']) }, createDto['fieldMetadata']);
   }
 
   async remove(id: number) {

package/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node -e:*)",
-      "WebFetch(domain:docs.solidxai.com)",
-      "WebFetch(domain:github.com)",
-      "Read(//Users/oswald/projects/Solid_Starters/solidctl/**)",
-      "Read(//Users/oswald/projects/Solid_Starters/**)",
-      "Bash(find /Users/oswald/projects/Solid_Starters/solid-core-module -type d -name migration* -o -name *database*)",
-      "Bash(node verify-imports.js)"
-    ],
-    "additionalDirectories": [
-      "/Users/oswald/projects/Solid_Starters/solidctl"
-    ]
-  }
-}

package/CLAUDE.md

@@ -1,26 +0,0 @@
-# This is the SolidX API project.
-This is included as a dependency in consuming projects.
-
-# SolidX UI
-# The corresponding UI project is at the below path:
- /Users/oswald/projects/Solid_Starters/solid-core-ui
-
-# SolidX Docs
-# The documentation project is at the below path:
-/Users/oswald/projects/solidxai-docs
-
-# SolidX Agent
-# The agent project which has the skills for helping users configure, build and use SolidX is at the below path:
-/Users/oswald/projects/Solid_Starters/agent
-
-# SolidX Control Plane Commands
-# The control plane commands for managing SolidX instances are in the below path:
-/Users/oswald/projects/Solid_Starters/solidctl
-
-# Testing reference project 
-# This is the reference library management project that is used for testing and development of SolidX features. It is located at the below path:
-/Users/oswald/projects/Solid_Starters/solid-library-management
-
-# Code Builder project
-# This is the project that contains the code builder which generates code based on user input and templates. It is located at the below path:
-/Users/oswald/projects/Solid_Starters/solid-code-builder

package/src/services/1.js

@@ -1,6 +0,0 @@
-1. Do i need to create a storeStreams method for aws service too?
-    - Handle later
-2. queues handling -> if queues is enabled by default, i.e triggerExport(exportTransactionEntity.id).
-    - startExport should either return the data or return the transaction id
-3. How to handle scenarios wherein, nested related exist.(do i need to only get the userkey)
-    - show the userKey