# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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.