⚙️ FEATURE-#22: Refactor template execution contract around dotflow start --workflow factory

cloud/alibaba-fc-scheduled/README.md

@@ -56,7 +56,7 @@ The timer trigger uses **cron expressions** (China Standard Time — UTC+8):
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — `s.yaml` references `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The `s.yaml` has the function name, region, container image, and schedule pre-configured from cookiecutter
 - Timer triggers use China Standard Time (CST/UTC+8) by default
 - To change the schedule after deploy, edit `cronExpression` in `s.yaml` and run `s deploy` again

cloud/alibaba-fc-scheduled/handler.py

@@ -7,5 +7,5 @@
 
 def handler(event, context):
     """Invoked by Timer Trigger on a schedule."""
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/alibaba-fc/README.md

@@ -45,6 +45,6 @@ s logs --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — `s.yaml` references `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The `s.yaml` has the function name, region, and container image pre-configured from cookiecutter
 - To add triggers (HTTP, timer, OSS, etc.), edit the `triggers` section in `s.yaml`

cloud/alibaba-fc/handler.py

@@ -6,5 +6,5 @@
 
 
 def handler(event, context):
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/azure-container/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/cloud-run-scheduled/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/cloud-run-scheduled/README.md

@@ -35,7 +35,7 @@ gcloud logging read "resource.type=cloud_run_revision AND resource.labels.servic
 
 ## Important
 
-- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The `cloudbuild.yaml` references `gcp_project_id` and `gcp_region` — these must match your GCP project
 - Replace `<cloud_run_url>` with the actual URL from the `gcloud run deploy` output
 - The scheduler uses OIDC authentication to invoke the Cloud Run service

cloud/cloud-run/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/cloud-run/README.md

@@ -27,6 +27,6 @@ gcloud logging read "resource.type=cloud_run_revision AND resource.labels.servic
 
 ## Important
 
-- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The `cloudbuild.yaml` references `gcp_project_id` and `gcp_region` — these must match your GCP project
 - Enable all required APIs before deploying

cloud/digital-ocean/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/docker/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/docker/README.md

@@ -15,5 +15,5 @@ docker compose up
 
 ## Important
 
-- Do not rename the `workflow.py` module or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The `docker-compose.yml` uses the `project_name` as container name

cloud/dotflow-cloud/README.md

@@ -0,0 +1,28 @@
+# Dotflow Cloud
+
+Managed execution runtime for dotflow pipelines. Run your workflow on Dotflow Cloud without managing infrastructure.
+
+## Workflow entrypoint
+
+Your `workflow.py` must expose a `main()` factory that returns a `DotFlow` instance:
+
+```python
+from dotflow import DotFlow
+
+def main() -> DotFlow:
+    workflow = DotFlow()
+    workflow.task.add(step=[...], initial_context=...)
+    return workflow
+```
+
+Dotflow Cloud runs it with the same contract used by:
+
+```bash
+dotflow start --workflow <module>.workflow:main
+```
+
+## Deploy
+
+```bash
+dotflow deploy --platform dotflow-cloud --project <project_name>
+```

cloud/ecs-scheduled/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/ecs-scheduled/README.md

@@ -40,7 +40,7 @@ aws logs get-log-events --log-group-name /ecs/<project_name> \
 
 ## Important
 
-- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The schedule expression in `template.yaml` uses AWS EventBridge syntax
 - Edit `aws_account_id` and `aws_region` in `template.yaml` before deploying
 - The ECS task runs on Fargate and stops after the workflow completes

cloud/ecs/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/ecs/README.md

@@ -53,7 +53,7 @@ aws logs get-log-events --log-group-name /ecs/<project_name> \
 
 ## Important
 
-- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The `task-definition.json` references the ECR image URI, `executionRoleArn`, and CloudWatch log group — do not change these unless you also update the corresponding AWS resources
 - The `aws_account_id` and `aws_region` must match your actual AWS account and region
 - Create the CloudWatch log group before running the task, otherwise the container will fail to start

cloud/fly-io/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/fly-io/fly.toml

@@ -5,7 +5,7 @@ primary_region = "iad"
   dockerfile = "Dockerfile"
 
 [processes]
-  worker = "python -m {{MODULE_NAME}}.workflow"
+  worker = "dotflow start --workflow {{MODULE_NAME}}.workflow:main --mode {{EXECUTION_MODE}}"
 
 [[vm]]
   cpu_kind = "shared"

cloud/github-actions/.github/workflows/dotflow.yml

@@ -17,4 +17,4 @@ jobs:
 
       - run: pip install -e .
 
-      - run: python -m {{MODULE_NAME}}.workflow
+      - run: dotflow start --workflow {{MODULE_NAME}}.workflow:main --mode {{EXECUTION_MODE}}

cloud/heroku/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/heroku/Procfile

@@ -1 +1 @@
-worker: python -m {{MODULE_NAME}}.workflow
+worker: dotflow start --workflow {{MODULE_NAME}}.workflow:main --mode {{EXECUTION_MODE}}

cloud/heroku/heroku.yml

@@ -5,6 +5,9 @@ build:
 run:
   worker:
     command:
-      - python
-      - -m
-      - {{MODULE_NAME}}.workflow
+      - dotflow
+      - start
+      - --workflow
+      - {{MODULE_NAME}}.workflow:main
+      - --mode
+      - {{EXECUTION_MODE}}

cloud/kubernetes/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/kubernetes/README.md

@@ -43,6 +43,6 @@ kubectl apply -f service.yaml
 
 ## Important
 
-- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` CMD depends on it
+- Do not rename `workflow.py` or the `main()` function — the `Dockerfile` runs `dotflow start --workflow <module>.workflow:main`
 - The `deployment.yaml` uses `imagePullPolicy: Never` by default — this only works with locally built images (minikube). For production, change to `Always` and use a container registry
 - Project names with `_` are automatically converted to `-` in Kubernetes resource names (RFC 1123 compliance)

cloud/lambda-api-trigger/README.md

@@ -45,6 +45,6 @@ sam logs --stack-name <project_name> --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — the `Dockerfile` CMD is `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The API Gateway URL is shown in the CloudFormation outputs after deploy
 - The `samconfig.toml` has stack name, region, and ECR repository pre-configured

cloud/lambda-api-trigger/handler.py

@@ -11,5 +11,5 @@ def handler(event, context):
     body = json.loads(event.get("body") or "{}")
     print(f"Received payload: {body}")
 
-    result = main()
+    main()
     return {"statusCode": 200, "body": json.dumps({"status": "workflow executed"})}

cloud/lambda-s3-trigger/README.md

@@ -41,6 +41,6 @@ sam logs --stack-name <project_name> --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — the `Dockerfile` CMD is `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - Edit the S3 bucket name and prefix in `template.yaml` before deploying
 - The `samconfig.toml` has stack name, region, and ECR repository pre-configured

cloud/lambda-s3-trigger/handler.py

@@ -7,5 +7,5 @@
 
 def handler(event, context):
     """Invoked by S3 file upload."""
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/lambda-scheduled/README.md

@@ -35,6 +35,6 @@ sam logs --stack-name <project_name> --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — the `Dockerfile` CMD is `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The schedule expression in `template.yaml` uses AWS EventBridge syntax (e.g. `rate(6 hours)`, `cron(0 12 * * ? *)`)
 - The `samconfig.toml` has stack name, region, and ECR repository pre-configured

cloud/lambda-scheduled/handler.py

@@ -7,5 +7,5 @@
 
 def handler(event, context):
     """Invoked by EventBridge on a schedule."""
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/lambda-sqs-trigger/README.md

@@ -41,6 +41,6 @@ sam logs --stack-name <project_name> --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — the `Dockerfile` CMD is `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The SQS queue is created by the SAM template — check `template.yaml` for queue configuration
 - The `samconfig.toml` has stack name, region, and ECR repository pre-configured

cloud/lambda-sqs-trigger/handler.py

@@ -12,5 +12,5 @@ def handler(event, context):
         body = json.loads(record.get("body", "{}"))
         print(f"Received message: {body}")
 
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/lambda/README.md

@@ -35,6 +35,6 @@ sam logs --stack-name <project_name> --tail
 ## Important
 
 - Do not rename `handler.py` or the `handler()` function — the `Dockerfile` CMD is `handler.handler`
-- Do not rename `workflow.py` or the `main()` function — `handler.py` imports it
+- Do not rename `workflow.py` or the `main()` function — `handler.py` calls `main()` which starts the workflow internally
 - The `samconfig.toml` has the stack name, region, and ECR repository pre-configured from cookiecutter
 - To change the schedule or add triggers, edit `template.yaml` (see `lambda-scheduled` template)

cloud/lambda/handler.py

@@ -6,5 +6,5 @@
 
 
 def handler(event, context):
-    result = main()
+    main()
     return {"statusCode": 200, "body": "workflow executed"}

cloud/railway/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cloud/railway/railway.json

@@ -5,7 +5,7 @@
     "dockerfilePath": "Dockerfile"
   },
   "deploy": {
-    "startCommand": "python -m {{MODULE_NAME}}.workflow",
+    "startCommand": "dotflow start --workflow {{MODULE_NAME}}.workflow:main --mode {{EXECUTION_MODE}}",
     "restartPolicyType": "ON_FAILURE",
     "restartPolicyMaxRetries": 3
   }

cloud/registry.json

@@ -5,6 +5,11 @@
       "description": "Dockerfile and docker-compose for local or any container runtime",
       "files": ["Dockerfile", "docker-compose.yml", "README.md"]
     },
+    "dotflow-cloud": {
+      "name": "Dotflow Cloud",
+      "description": "Managed dotflow runtime with workflow factory entrypoint (dotflow start --workflow)",
+      "files": ["README.md"]
+    },
     "lambda": {
       "name": "AWS Lambda",
       "description": "Dockerfile, handler.py, and SAM template for AWS Lambda",

cloud/render/Dockerfile

@@ -6,4 +6,4 @@ COPY . .
 
 RUN pip install --no-cache-dir -e .
 
-CMD ["python", "-m", "{{MODULE_NAME}}.workflow"]
+CMD ["dotflow", "start", "--workflow", "{{MODULE_NAME}}.workflow:main", "--mode", "{{EXECUTION_MODE}}"]

cookiecutter.json

@@ -6,5 +6,5 @@
     "execution_mode": ["sequential", "parallel", "background"],
     "retry": ["no", "yes"],
     "checkpoint": ["no", "yes"],
-    "cloud": ["none", "docker", "lambda", "lambda-scheduled", "lambda-s3-trigger", "lambda-sqs-trigger", "lambda-api-trigger", "ecs", "ecs-scheduled", "cloud-run", "cloud-run-scheduled", "kubernetes", "github-actions", "alibaba-fc", "alibaba-fc-scheduled"]
+    "cloud": ["none", "dotflow-cloud", "docker", "lambda", "lambda-scheduled", "lambda-s3-trigger", "lambda-sqs-trigger", "lambda-api-trigger", "ecs", "ecs-scheduled", "cloud-run", "cloud-run-scheduled", "kubernetes", "github-actions", "alibaba-fc", "alibaba-fc-scheduled"]
 }

hooks/post_gen_project.py

@@ -11,6 +11,7 @@
 CLOUD = "{{ cookiecutter.cloud }}"
 PROJECT_NAME = "{{ cookiecutter.project_name }}"
 MODULE_NAME = "{{ cookiecutter.module_name }}"
+EXECUTION_MODE = "{{ cookiecutter.execution_mode }}"
 
 BOLD = "\033[1m"
 CYAN = "\033[36m"
@@ -33,6 +34,7 @@ def ask_inputs() -> dict:
         "MODULE_NAME": MODULE_NAME,
         "STACK_NAME": sanitized_name,
         "K8S_NAME": sanitized_name,
+        "EXECUTION_MODE": EXECUTION_MODE,
     }
 
     if CLOUD in {

{{cookiecutter.project_name}}/README.md

@@ -16,7 +16,7 @@ A workflow built with [dotflow](https://github.com/dotflow-io/dotflow).
 
 ```bash
 pip install -e ".[dev]"
-python -m {{ cookiecutter.module_name }}.workflow
+dotflow start --workflow {{ cookiecutter.module_name }}.workflow:main --mode {{ cookiecutter.execution_mode }}
 ```
 
 ## Running Tests

{{cookiecutter.project_name}}/pyproject.toml

@@ -1,15 +1,17 @@
+{%- set scheduled_clouds = ["dotflow-cloud", "lambda-scheduled", "ecs-scheduled", "cloud-run-scheduled", "alibaba-fc-scheduled", "github-actions"] -%}
+{%- set scheduler = "none" if cookiecutter.cloud in scheduled_clouds else cookiecutter.scheduler -%}
 [project]
 name = "{{ cookiecutter.project_name }}"
 version = "0.1.0"
 description = ""
 requires-python = ">=3.9"
 dependencies = [
-{% if cookiecutter.storage == "s3" and cookiecutter.scheduler == "cron" %}    "dotflow==0.15.0.dev7[aws,scheduler]",
-{% elif cookiecutter.storage == "gcs" and cookiecutter.scheduler == "cron" %}    "dotflow==0.15.0.dev7[gcp,scheduler]",
-{% elif cookiecutter.storage == "s3" %}    "dotflow==0.15.0.dev7[aws]",
-{% elif cookiecutter.storage == "gcs" %}    "dotflow==0.15.0.dev7[gcp]",
-{% elif cookiecutter.scheduler == "cron" %}    "dotflow==0.15.0.dev7[scheduler]",
-{% else %}    "dotflow==0.15.0.dev7",
+{% if cookiecutter.storage == "s3" and scheduler == "cron" %}    "dotflow==1.0.0.dev3[aws,scheduler]",
+{% elif cookiecutter.storage == "gcs" and scheduler == "cron" %}    "dotflow==1.0.0.dev3[gcp,scheduler]",
+{% elif cookiecutter.storage == "s3" %}    "dotflow==1.0.0.dev3[aws]",
+{% elif cookiecutter.storage == "gcs" %}    "dotflow==1.0.0.dev3[gcp]",
+{% elif scheduler == "cron" %}    "dotflow==1.0.0.dev3[scheduler]",
+{% else %}    "dotflow==1.0.0.dev3",
 {% endif %}]
 
 [project.optional-dependencies]