XCON Workflow

XCON Workflow is a public, safe-by-default toolkit for XCON-style action workflows. It parses SKETCH and JSON workflows, normalizes them, validates safety boundaries, renders Mermaid/HTML graphs, and produces dry-run traces.

It does not execute shell commands, network calls, filesystem actions, browser APIs, or host application logic.

Install

npm install @xcon-workflow/core
npm install @xcon-workflow/markdown-it

Why

XCON actions are useful not only as runtime behavior, but also as documentation:

• Button and screen navigation flows
• onLoad, onClick, success, and failure action graphs
• Server-side xNode workflow diagrams
• CI or batch job sketches that can be reviewed before execution
• Markdown and Figma-friendly block diagrams

Packages

• @xcon-workflow/core: parser, normalizer, validator, graph builder, Mermaid/HTML renderer, dry-run trace
• @xcon-workflow/markdown-it: Markdown fence renderer for workflow diagrams

SKETCH Example

workflow "Product detail click"
  intent: note "Persist the selected item before opening the detail screen"
  saveSelected: saveData
    target "global"
    key "selectedProductId"
    data "= item.id"
  openDetail: activity "screens/product-detail.xconj"
    after saveSelected

JSON Example

{
  "type": "batch",
  "mode": "queue",
  "actions": [
    {
      "type": "saveData",
      "target": "global",
      "key": "selectedProductId",
      "data": "= item.id"
    },
    {
      "type": "activity",
      "xcon": "screens/product-detail.xconj"
    }
  ]
}

API

import {
  parseWorkflow,
  parseWorkflowSketch,
  normalizeWorkflow,
  validateWorkflow,
  buildWorkflowGraph,
  workflowToMermaid,
  renderWorkflowHtml,
  dryRunWorkflow
} from '@xcon-workflow/core';

const workflow = parseWorkflowSketch(source);
const workflowFromAnyInput = parseWorkflow(source);
const diagnostics = validateWorkflow(workflow);
const graph = buildWorkflowGraph(workflow);
const mermaid = workflowToMermaid(workflow);
const html = renderWorkflowHtml(workflow);
const trace = dryRunWorkflow(workflow);

If you need parseWorkflow, it handles JSON object, JSON string, and SKETCH input and delegates through normalize/parsing.

Security Boundary

The public package treats these as symbolic nodes:

• callApi, command, shell, script, custom
• file actions such as saveFile and openFile
• UI host actions such as activity, goBack, setObjectValues, setNewData

note is documentation-only and is intended for agenda steps, manual milestones, and explanatory diagram nodes.

Use this project to inspect, lint, document, and visualize workflows. Do not treat it as a general automation runner.

Release and Distribution Notes

• Publish targets are workspace packages only:
  • @xcon-workflow/core
  • @xcon-workflow/markdown-it
• The root package (xcon-workflow) is private and is not published.
• Markdown and playground documentation:
  • docs/ includes public docs
  • examples/ includes sample workflow sources
  • playground/ contains index.html and markdown.html
  • npm run playground runs a local static server

Quick Checks Before Release

• npm run check:alpha
• npm test
• ensure no legacy public-facing terms or non-English text in public files
• npm publish --workspace @xcon-workflow/core
• npm publish --workspace @xcon-workflow/markdown-it