Semantic lifecycle workflows

drawio-tools keeps editable Draw.io XML and semantic Diagram IR v2 synchronized without requiring Draw.io Desktop, a browser, network access, Python, Graphviz, or ELK.

All examples run from scripts/ after pnpm install --frozen-lockfile and task build. Results are YAML on standard output. Commands that write files require an explicit --output and use an atomic temporary-file rename. Input files cannot be used as output aliases.

Import and round trip

node dist/cli/commands.js --action import \
  --file architecture.drawio \
  --output architecture.yaml

node dist/cli/commands.js --action build \
  --file architecture.yaml \
  --output rebuilt.drawio

Import accepts bare mxGraphModel documents and multi-page mxfile wrappers. It preserves stable cell IDs, labels (including deliberately empty labels), parent relationships, styles, geometry, waypoints, semantic metadata, wrapper/page/model attributes, and unknown XML children in $drawio preservation envelopes. Dangling endpoints and ambiguous identities fail closed. Import output must use .yaml, .yml, or .json.

Transactional editing

node dist/cli/commands.js --action edit \
  --file architecture.yaml \
  --spec ../examples/edit-batch.yaml \
  --dry-run

node dist/cli/commands.js --action edit \
  --file architecture.yaml \
  --spec ../examples/edit-batch.yaml \
  --output edited.drawio

A batch targets one page and supports typed add, update, move, delete, and connect operations. Supported preconditions are exists, not-exists, and property-equals, each expressed with a type and id. Unknown precondition or operation types, update payloads that attempt to change id, duplicate identifiers, invalid parents/endpoints, and non-cascading deletion of referenced elements fail closed and abort the entire batch. Dry runs return a preview and write nothing.

Linked audience views

node dist/cli/commands.js --action views \
  --file architecture.yaml \
  --views executive,system,deployment,dataflow,security \
  --output linked-views.drawio

Views preserve source model identifiers and provenance. A sparse view records an explicit fallback reason and modeling hint rather than pretending complete coverage. Unknown view names fail closed.

Query and paths

node dist/cli/commands.js --action query --file architecture.yaml --kind service
node dist/cli/commands.js --action query --file architecture.yaml \
  --property owner=platform --property 'production=true'
node dist/cli/commands.js --action query --file architecture.yaml \
  --from client --to database

Queries filter by semantic kind and exact properties. --from plus --to returns a deterministic shortest directed path. Semantic operations require globally unambiguous node IDs across pages.

Architecture policy tests

node dist/cli/commands.js --action test --file architecture.yaml
node dist/cli/commands.js --action test --file architecture.yaml \
  --spec ../examples/policy-rules.yaml --strict

Built-in policy identifiers:

no-direct-internet-to-database
no-cycles
no-orphans
every-service-has-owner
production-has-observability
external-dependencies-have-timeouts
trust-boundaries-use-protocol

Errors always fail. With --strict, warnings also fail. Unknown policy identifiers fail closed.

Failure what-if analysis

node dist/cli/commands.js --action what-if \
  --file architecture.yaml --fail api

The simulation follows outgoing dependencies and stops propagation at an edge with properties.isolates_failure: true. It never mutates the source model.

Three-way synchronization

node dist/cli/commands.js --action sync \
  --base generated-before.yaml \
  --file manually-edited.yaml \
  --spec generated-after.yaml \
  --output synchronized.drawio

The base is the previous generated model, --file is the manually edited model, and --spec is the newly generated model. Synchronization preserves manual geometry/style, adds incoming identities, and reports semantic conflicts. Removed elements and pages are retained with lifecycle metadata by default; use --prune to remove them explicitly. Add --dry-run to return a preview without writing.

Offline story

node dist/cli/commands.js --action story \
  --file architecture.yaml \
  --fail api \
  --output architecture-story.html

The output is one self-contained HTML file with a restrictive Content Security Policy, escaped labels, keyboard navigation, a complete text alternative, provenance, and an optional what-if overlay. It makes no external requests and uses square corners.

Doctor

node dist/cli/commands.js --action doctor

Doctor reports availability of optional local backends without launching them and confirms that the native core does not require network access.

4.8 KiB Raw Blame History