freezonex/tier0-skill/flow

tier0-flow

Use this skill for Tier0 Node-RED Flow management.

Use When

• The user wants to list, inspect, create, update, or delete Flows.
• The user wants to export Node-RED canvas JSON.
• The user wants to deploy or replace a Node-RED canvas.
• The user asks about SourceFlow or EventFlow state.
• The user wants industrial protocol collection, including Tier0's own tier0-opcua-* nodes.
• The user wants to expose or call a webhook or application endpoint implemented with Node-RED http in and http response nodes.

Do Not Use When

• The user wants current UNS topic values. Use uns/references/read.md.
• The user wants to directly drag nodes in the Node-RED UI. The CLI imports and exports JSON; UI editing happens in a browser.
• The user wants protocol mapping details. Read the matching protocol reference first.
• The user wants Node-RED Admin API access. The gateway blocks Admin paths; use the CLI Flow management commands instead.

Non-Negotiable Rules

1. List before acting when the Flow ID is unknown.
2. CLI commands use integer id; Node-RED flowId is not a CLI identifier.
3. Before deploy, export a backup: tier0 flow data --id <id> --out backup.json.
4. Preview agent-generated mutations with --dry-run --json; this is required before deploy and delete.
5. flow deploy and flow delete require --yes after user confirmation.
6. Deleting a Flow stops the related Node-RED container.
7. Do not construct deploy payloads before reading references/deploy.md.
8. Preserve the backend-created Tier0 mqtt-broker config node. Do not create or replace it.
9. Use /flow/{source|event}/** only for user-defined http in endpoints. Never use it for Flow management or Node-RED Admin APIs.
10. Call http in endpoints with tier0 api; do not add or assume a separate flow invoke command.

Flow Types

Routing

Protocol References

Read the matching file before generating or editing Flow JSON:

For new OPC-UA Flows, prefer @tier0/opcua-client when its required node types are enabled in the runtime. Check flow nodes first. Preserve existing community-node Flows unless migration is requested; the two packages have different config fields and message formats and are not interchangeable.

Common Commands

tier0 flow list
tier0 flow list --source --json
tier0 flow get --id 1 --json
tier0 flow create --name "modbus-collector" --source --desc "Modbus TCP collector"
tier0 flow create --name "alert-handler" --event --desc "Temperature alarm processor"
tier0 flow data --id 1 --out flows.json
tier0 flow deploy --id 1 -f flows.json --dry-run --json
# after user confirmation
tier0 flow deploy --id 1 -f flows.json --yes

Node-RED Canvas Workflow

tier0 flow list
tier0 flow data --id <id> --out backup.json
# edit or generate flows.json
tier0 flow deploy --id <id> -f flows.json --dry-run --json
# show the preview and impact; wait for user confirmation
tier0 flow deploy --id <id> -f flows.json --yes

When generating flows.json, include the existing backend-created Tier0 mqtt-broker config node from the exported data. Node-RED credentials are stored against the node ID; replacing that node can cause anonymous MQTT connections and authentication failure.

tier0 flow data --out flows.json writes a deployable Node-RED flows array. The file can be edited, previewed with tier0 flow deploy -f flows.json --dry-run --json, and deployed with --yes after user confirmation.

Structured Errors

With --json, read failures from stderr and branch on error.type, error.subtype, and error.param. Fix invalid_argument at the named parameter instead of retrying unchanged. Exit code 10 with confirmation_required means the user must approve the high-risk operation before --yes is added.