@solidxai/core 0.1.12-beta.0 → 0.1.12-beta.2

package/docs/workflow/hello-world-example-notes.md

@@ -0,0 +1,271 @@
+# Hello World Example Notes
+
+## Purpose
+
+This document captures a simple reference workflow with:
+
+- a disabled schedule trigger
+- one workflow input
+- a linear task sequence
+- cross-task output references in the final log message
+
+Compared with the other examples, this one is intentionally simple and is useful as the baseline topology for a trigger-driven sequential workflow.
+
+---
+
+## Example Workflow YAML
+
+```yaml
+id: hello-world
+namespace: tutorial
+labels:
+  name: Hello World
+
+triggers:
+  - id: daily
+    type: io.kestra.plugin.core.trigger.Schedule
+    cron: 0 9 * * *
+    disabled: true
+
+inputs:
+  - id: user
+    type: STRING
+    defaults: Rick Astley
+
+tasks:
+  - id: first_task
+    type: io.kestra.plugin.core.output.OutputValues
+    description: Return a value used later in the logged greeting.
+    values:
+      message: "thrilled"
+
+  - id: second_task
+    type: io.kestra.plugin.scripts.shell.Commands
+    description: Run quick shell commands and expose a value as output.
+    commands:
+      - sleep 0.42
+      - echo '::{"outputs":{"returned_data":"mydata"}}::'
+
+  - id: hello_world
+    type: io.kestra.plugin.core.log.Log
+    description: Log a welcome message using the inputs and earlier outputs.
+    message: |
+      Welcome to Kestra, {{ inputs.user }}! 
+      We are {{ outputs.first_task.values.message }} to have you. Here is your output from the second task: {{outputs.second_task.vars}}.
+
+description: |
+  **Use case:** Intro to Kestra that collects a `user` input and writes a friendly log.
+  **Trigger:** Disabled daily run at 09:00, left in place to show how scheduling works.
+  **Highlights:**
+  - Emit sample values to demonstrate how outputs travel between tasks.
+  - Run a shell command and surface its output for downstream use.
+  - Log the combined greeting using both inputs and prior outputs.
+```
+
+---
+
+## What This Example Adds
+
+This example is useful because it is the cleanest reference for:
+
+- a simple trigger group
+- a simple top-level input
+- a purely linear task flow
+- output propagation across multiple tasks
+- a beginner-friendly workflow shape
+
+It is a good baseline workflow to validate that the editor handles the most common happy path before layering in control flow and nested groups.
+
+---
+
+## High-Level Structure
+
+```text
+Triggers
+└── daily
+
+Main Flow
+first_task
+  |
+  v
+second_task
+  |
+  v
+hello_world
+```
+
+Another useful linear representation:
+
+```text
+Start
+  |
+  v
+[trigger group: daily]
+  |
+  v
+first_task
+  |
+  v
+second_task
+  |
+  v
+hello_world
+  |
+  v
+End
+```
+
+---
+
+## Main Note
+
+### Example With Trigger
+
+This is the key point of this example.
+
+It confirms the simpler trigger case:
+
+- one schedule trigger
+- one straight-line task chain
+- no branching
+- no nested control-flow container
+
+This makes it a strong baseline reference for trigger-aware topology rendering.
+
+---
+
+## Trigger Notes
+
+The screenshots again reinforce the trigger-group treatment:
+
+- triggers appear in a dedicated grouped region
+- they are visually distinct from normal tasks
+- the group connects into the main workflow sequence
+- disabled triggers are still shown
+
+For SolidX:
+
+- the trigger group should remain visible in both topology and edit views
+- disabled state should be preserved in the rendered metadata
+- trigger visualization should not require trigger editing to be complete
+
+---
+
+## Inputs Notes
+
+This example includes one top-level input:
+
+- `user`
+
+That makes it useful as a lightweight reference for workflow-level inputs without the extra complexity of multiple configurable runtime endpoints.
+
+The workflow editor will eventually need to support:
+
+- displaying workflow inputs clearly
+- editing them through code first
+- later, optionally surfacing them in a schema-driven workflow settings experience
+
+---
+
+## Output Propagation Notes
+
+This example is also a nice reference for how outputs flow between tasks.
+
+### Output Usage Pattern
+
+- `first_task` emits `values.message`
+- `second_task` emits shell-derived output data
+- `hello_world` consumes both
+
+This is useful for docs and UI because it demonstrates:
+
+- task outputs are part of the workflow authoring experience
+- users need help understanding available upstream outputs
+- code completion and docs should eventually assist with these references
+
+The final log task is effectively a small example of expression-aware authoring.
+
+---
+
+## Topology Notes
+
+The topology for this workflow is intentionally minimal:
+
+- trigger group at the top
+- one vertical line of tasks
+- no branches
+- no nested containers
+
+This means it should be treated as the baseline layout contract for simple workflows.
+
+If this example renders poorly, the editor is not yet ready for the more advanced ones.
+
+---
+
+## Edit View Notes
+
+The edit screenshot again supports the same basic composition:
+
+- left: code
+- right: flow
+
+This example is especially useful here because the structure is easy to visually verify against the YAML without much interpretation.
+
+That makes it a good smoke-test workflow for:
+
+- YAML-to-flow transformation
+- trigger rendering
+- icon mapping
+- sequential node spacing
+- add/edit/delete affordances
+
+---
+
+## Implications For SolidX
+
+This example should be used as the default sanity-check workflow for the editor because it combines:
+
+- trigger presence
+- inputs
+- outputs
+- sequential task chaining
+
+without introducing:
+
+- branching
+- grouping containers
+- nested child tasks
+
+So it is likely the best first example for verifying the full authoring loop.
+
+---
+
+## Pending Feature Notes
+
+This example highlights a few future UX improvements:
+
+- workflow-level input editing surface
+- output reference assistance in code editing
+- trigger-specific docs and status rendering
+- task output discovery in the docs side panel or schema editor
+
+---
+
+## Screenshot References
+
+These screenshots informed the notes above:
+
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.14.06.png`
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.14.19.png`
+
+---
+
+## Recommended Follow-On Use
+
+This example should be used as a reference for:
+
+1. simple trigger-group rendering
+2. linear workflow layout validation
+3. workflow input handling
+4. output-reference awareness in authoring
+5. smoke-testing the end-to-end code-to-flow editor behavior

package/docs/workflow/kestra-concepts-plugins-blueprints.md

@@ -0,0 +1,315 @@
+# Kestra Concepts, Plugins, and Blueprints
+
+This note summarizes the Kestra Academy pages from the `Concepts` section plus the `Plugins` and `Blueprints` lessons. The goal is to translate Kestra's mental model into design inputs for a reusable SolidX workflow engine and builder module.
+
+## Flows
+
+A flow is the top-level workflow container. It defines:
+
+- a unique `id`
+- a `namespace`
+- the `tasks` that perform the work
+
+Kestra treats the flow as the unit of orchestration. The flow holds both the tasks and the orchestration logic that determines how those tasks relate. Flows can be authored in YAML, through a no-code editor, or with AI assistance.
+
+Important behavior:
+
+- Every flow belongs to a namespace
+- Namespaces act like hierarchical folders
+- Flow `id` and `namespace` become permanent after save
+
+### Design implication for us
+
+We will need a first-class workflow definition aggregate with stable identity, logical grouping, versioning, and a representation that can support both code-based and visual editing.
+
+## Tasks
+
+Tasks are the individual executable steps in a flow. They perform discrete actions such as:
+
+- calling an API
+- running code
+- querying a database
+- sending a notification
+
+Kestra highlights two broad task categories:
+
+- Runnable tasks: do actual work
+- Flowable tasks: control orchestration behavior
+
+Every task has at least:
+
+- `id`
+- `type`
+
+Task-specific properties then vary by plugin/task type.
+
+### Design implication for us
+
+Our model should distinguish between:
+
+- step identity
+- step type
+- step configuration
+- executable work steps versus control-flow steps
+
+This is likely the start of a polymorphic node model in our domain.
+
+## Inputs
+
+Inputs parameterize a flow so it can be executed with different values without changing the definition. Kestra inputs have:
+
+- `id`
+- `type`
+
+Common optional properties include:
+
+- `defaults`
+- `displayName`
+- `required`
+- `description`
+
+Kestra supports multiple input types such as string, integer, select, JSON, file, and URI. Inputs are referenced via expressions like `{{ inputs.name }}`.
+
+### Design implication for us
+
+We need a typed workflow input model with validation, defaults, UI metadata, and runtime binding support. Inputs should be usable both at manual execution time and by automated triggers.
+
+## Outputs
+
+Outputs are runtime results produced by tasks. They are stored in the execution context and made available to downstream tasks. Outputs can be:
+
+- simple values
+- structured data
+- files
+
+They are referenced using expressions like `{{ outputs.task_id.output_value }}`.
+
+Kestra also introduces the idea that an entire flow can expose outputs, not just tasks.
+
+### Design implication for us
+
+We need an execution context model that can store and resolve:
+
+- per-step outputs
+- flow-level outputs
+- file or artifact references
+
+This becomes a core part of runtime execution and expression resolution.
+
+## Triggers
+
+Triggers automate flow execution. Kestra describes them as the "when" of a workflow. Examples include:
+
+- schedules
+- polling
+- realtime events
+- webhooks
+- flow completion triggers
+
+Triggers have their own `id`, `type`, and type-specific configuration. They can also pass input values into a flow when they fire. A single flow can have multiple triggers.
+
+### Design implication for us
+
+We need a first-class trigger model that supports:
+
+- multiple trigger instances per workflow
+- trigger-specific configuration
+- input injection
+- manual and automated execution paths
+
+This likely means triggers should be separate domain entities attached to a workflow definition rather than being embedded as anonymous config blobs only.
+
+## Expressions
+
+Expressions are the dynamic binding and transformation layer. Kestra uses `{{ }}` syntax and allows access to runtime context such as:
+
+- `inputs`
+- `outputs`
+- `flow`
+- `execution`
+- `trigger`
+
+Expressions can do more than variable lookup. They can:
+
+- transform values
+- parse JSON
+- format dates
+- perform calculations
+
+### Design implication for us
+
+We need to make an early architectural decision about the expression system:
+
+- whether to design our own expression format
+- whether to embed an existing engine
+- what execution context objects are exposed
+- how expressions are validated at design time versus resolved at runtime
+
+This is a foundational concern because it affects inputs, outputs, conditions, triggers, and task configuration.
+
+## Flowable Tasks
+
+Flowable tasks control orchestration instead of doing business work directly. Kestra highlights patterns such as:
+
+- conditional branching with `If` and `Switch`
+- iteration with `ForEach`, `ForEachItem`, and `LoopUntil`
+- parallel execution
+- subflows for reuse
+
+These tasks combine orchestration rules with expressions.
+
+### Design implication for us
+
+Our workflow graph cannot be modeled as only a flat list of steps. We will need support for:
+
+- branching
+- nesting
+- loops
+- fan-out / parallelism
+- reusable subflow invocation
+
+This pushes us toward a graph or tree-plus-edges model rather than a simple sequential pipeline model.
+
+## Execution
+
+An execution is a single run of a flow. Each execution contains task runs, and each task run has its own runtime behavior, outputs, logs, and status.
+
+Kestra emphasizes:
+
+- execution states such as created, running, success, failed
+- observability through logs, metrics, outputs, topology, and timing views
+- replaying failed task runs or entire executions
+- revisions of flow definitions
+
+### Design implication for us
+
+We should model workflow definition and workflow execution separately. At minimum, our domain will likely need:
+
+- workflow definitions
+- workflow revisions
+- workflow executions
+- step executions
+- execution state transitions
+- logs / metrics / artifacts
+- replay or rerun semantics
+
+## Secrets
+
+Secrets are sensitive values stored outside workflow definitions and referenced at runtime. Kestra exposes them through expressions via a `secret()` function and avoids leaking them into code, logs, and outputs.
+
+### Design implication for us
+
+We need a secret reference strategy, not just plain text fields. The module should support:
+
+- secure secret references in workflow definitions
+- runtime secret resolution
+- masking in logs and UI
+- separation between design-time config and sensitive runtime values
+
+## Plugins
+
+Plugins are the extension mechanism that powers tasks and triggers. In Kestra's framing, plugins are the integration and capability layer that connects workflows to:
+
+- programming runtimes
+- databases
+- APIs
+- cloud systems
+- notification channels
+
+Even "core" capabilities are still exposed as plugin-backed task or trigger types.
+
+### Design implication for us
+
+This is especially important for our module. We should not hard-code every possible step type into the core engine. We likely need:
+
+- a reusable action/task type registry
+- typed configuration schemas per task type
+- trigger type registry
+- optional packaging/distribution story for reusable step providers
+
+In SolidX terms, this may become one of the primary extensibility points of the module.
+
+## Blueprints
+
+Blueprints are curated, ready-to-use example workflows. Kestra presents them as:
+
+- working code
+- documentation
+- tags for discovery
+
+They are meant to accelerate adoption by giving users validated examples that can be copied and adapted.
+
+### Design implication for us
+
+A reusable workflow builder module will benefit from a blueprint/template system from the start or at least early in the roadmap. Blueprints can help with:
+
+- onboarding
+- discoverability
+- best-practice reuse
+- sample implementations of step types and orchestration patterns
+
+## Cross-Cutting Observations
+
+Kestra's model repeatedly separates concerns in a very clean way:
+
+- Definition versus execution
+- Work steps versus control-flow steps
+- Static configuration versus runtime context
+- Secure references versus plain values
+- Core engine versus plugin-provided capabilities
+
+That separation is probably the biggest lesson for our design.
+
+## Likely Domain Areas For Our SolidX Module
+
+Based on these lessons, our reusable module will probably need domain models for at least:
+
+- Workflow definition
+- Workflow revision
+- Workflow namespace or foldering concept
+- Workflow input
+- Workflow output
+- Trigger
+- Step / task
+- Step type registry
+- Step execution
+- Workflow execution
+- Execution logs and artifacts
+- Secret reference
+- Blueprint / template
+
+## Metadata / DSL Implication
+
+Kestra uses YAML as a human-readable workflow definition format. For our SolidX module, we should expect to define an equivalent metadata representation for workflows that can support:
+
+- stable workflow identity
+- typed nodes
+- nested control-flow structures
+- trigger definitions
+- expressions
+- reusable references
+- versioning
+
+That representation will need to work for both:
+
+- a visual workflow builder
+- a code or JSON/YAML style export/import story
+
+## Sources
+
+- [Flows](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404093-flows)
+- [Tasks](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404094-tasks)
+- [Inputs](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404096-inputs)
+- [Outputs](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404097-outputs)
+- [Triggers](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404103-triggers)
+- [Expressions](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404099-expressions)
+- [Flowable Tasks](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404106-flowable-tasks)
+- [Execution](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404107-execution)
+- [Secrets](https://academy.kestra.io/p/courses/kestra-fundamentals/3492614-concepts/11404115-secrets)
+- [Plugins](https://academy.kestra.io/p/courses/kestra-fundamentals/3492618-plugins-blueprints/11437898-plugins)
+- [Blueprints](https://academy.kestra.io/p/courses/kestra-fundamentals/3492618-plugins-blueprints/11437900-blueprints)
+
+## Notes
+
+- The extracted lesson text was pulled from the Academy pages directly.
+- Some lessons included image-heavy examples, so the summary focuses on the textual teaching content plus explicit design implications for our module.