diff --git a/README.md b/README.md index 65b9d24..f9b808c 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,20 @@ Commands fail closed on ambiguous identities, invalid view/policy names, input/o --- +### Native service libraries + +The combined package also exposes tested TypeScript service APIs for capabilities that are not registered as CLI actions: + +| Family | Implemented native services | +|---|---| +| Safe source importers | Python, JavaScript/TypeScript, Go, Rust, Terraform, Kubernetes, Docker Compose, SQL, OpenAPI, and CI job DAG subsets | +| Toolbox | Five themes, generic offline shape search, Mermaid and Markdown reverse transforms, semantic diff, strict relabeling, and accessible metric heatmaps | +| Specialized profiles | C4, sequence, tube map, executive compression, runbook HTML, timelapse, and dependency-ordered build-up | + +These are conservative, bounded service contracts rather than claims of complete language parsers or peer-compatible command-line interfaces. See [`references/agents365-capability-coverage.md`](references/agents365-capability-coverage.md) for the strict 42-tool comparison and remaining gaps. + +--- + ### Inventory #### `summary` diff --git a/SKILL.md b/SKILL.md index fb4be6a..695c130 100644 --- a/SKILL.md +++ b/SKILL.md @@ -13,12 +13,15 @@ compatibility: Designed for Cline, Claude Code, GitHub Copilot, OpenAI Codex, an # Draw.io Diagram Skill -This skill covers four capability families: +This skill covers seven capability families: 1. **Deterministic YAML generation** — validate v1/v2 semantic Diagram IR and build native multi-page `.drawio` XML with stable IDs, dependency-aware layout, and obstacle-aware routing 2. **Direct XML generation** — create `.drawio` files (and optionally export to PNG/SVG/PDF) from a description or requirements 3. **Diagram analysis** — run the `drawio-tools` CLI to analyse an existing `.drawio` file: inventory shapes and connectors, validate layout quality, detect overlaps/orphans, and recommend page sizes 4. **Semantic lifecycle** — loss-aware Draw.io import, transactional stable-ID edits, linked views, semantic query/policy/what-if analysis, three-way synchronization, and self-contained offline story publishing +5. **Safe source importers** — bounded native TypeScript subsets for Python, JavaScript/TypeScript, Go, Rust, Terraform, Kubernetes, Docker Compose, SQL, OpenAPI, and CI dependency graphs +6. **Toolbox transforms** — themes, offline generic shape search, reverse Mermaid/Markdown, semantic diff, strict relabeling, and accessible heatmaps +7. **Specialized profiles** — C4, sequence, tube map, compression, runbook, timelapse, and dependency-ordered build-up services **Reference files** (read these when using this skill): - [references/capabilities.md](./references/capabilities.md) — full list of capabilities and all CLI analysis actions an agent can execute @@ -29,6 +32,7 @@ This skill covers four capability families: - [references/routing-best-practices.md](./references/routing-best-practices.md) — corridor planning, routing patterns, overlap verification, swimlane routing, validation workflow - [references/maintenance.md](./references/maintenance.md) — maintaining and rebuilding the skill itself - [references/semantic-lifecycle.md](./references/semantic-lifecycle.md) — import, edit, views, query, policy, what-if, sync, story, and doctor workflows +- [references/agents365-capability-coverage.md](./references/agents365-capability-coverage.md) — strict evidence matrix for all 42 compared peer tools, including partial and deferred scope ## Available scripts @@ -66,6 +70,8 @@ task build See [references/capabilities.md](./references/capabilities.md) for what every action outputs. +Source importers, toolbox transforms, and specialized profiles are currently native TypeScript service APIs, not additional CLI actions. Do not invent action names for them; use the exported services or the documented lifecycle actions. + --- Generate draw.io diagrams as native `.drawio` files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io). diff --git a/references/agents365-capability-coverage.md b/references/agents365-capability-coverage.md new file mode 100644 index 0000000..5d7b91d --- /dev/null +++ b/references/agents365-capability-coverage.md @@ -0,0 +1,77 @@ +# Agents365 capability coverage + +> Evidence basis: clean-room behavioral comparison of 42 peer tools. Peer source and bundled assets were not copied because the inspected mirror had no complete license file. + +## Reading the classifications + +- **Implemented** — full mapped peer acceptance contract is available. +- **Partial** — useful native behavior is implemented, but some peer options, adapters, or Command-Line Interface (CLI) exposure remain. +- **Optional deferred** — environment-heavy capability remains outside the mandatory offline core. +- **Rejected** — capability was deliberately excluded from this phase. + +These are strict peer-parity labels. A `partial` row can still contain substantial production-ready native functionality. + +## Aggregate + +| Classification | Count | +|---|---:| +| Implemented | 0 | +| Partial | 29 | +| Optional deferred | 11 | +| Rejected | 2 | +| **Total** | **42** | + +## Capability matrix + +| Peer tool | Classification | Native evidence | Remaining gap | +|---|---|---|---| +| `aiicons.py` | **optional-deferred** | `scripts/src/services/shape-catalog/shape-catalog.ts`
`scripts/src/services/shape-catalog/shape-catalog.test.ts` | Only an eight-entry generic offline shape catalog exists; there is no AI/LLM brand manifest, variant selection, embedding adapter, URL allowlist, or CLI action. | +| `autolayout.py` | **partial** | `scripts/src/services/layout/layout-engine.ts`
`scripts/src/services/layout/layout-engine.test.ts`
`scripts/src/actions/build/action.ts` | Deterministic native layouts exist, but there is no peer-compatible graph-JSON adapter, group-tree contract, monochrome mode, or objective TB/LR tuning action. | +| `buildup.py` | **partial** | `scripts/src/services/profiles/buildup.ts`
`scripts/src/services/profiles/buildup.test.ts` | The service computes deterministic cumulative IR frames, but it does not parse Draw.io through a buildup action, render PNG frames, publish the player HTML, encode GIF, or expose CLI availability semantics. | +| `c4.py` | **partial** | `scripts/src/services/profiles/c4.ts`
`scripts/src/services/profiles/c4.test.ts`
`scripts/src/services/profiles/index.ts` | The service validates hierarchy and creates linked C4 pages, but no C4 CLI/action or input-file adapter is registered, and canonical peer style/direction options are not fully exposed. | +| `ciimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | The service imports a bounded generic jobs/needs object, but lacks CLI registration, repository workflow discovery, triggers, runners, matrices, reusable workflows, GitLab stages, and inferred stage dependencies. | +| `composeimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | Services, depends_on, and simple named volumes are covered through a service API; links, volumes_from, long-form mounts, network grouping, conventional-file discovery, and CLI exposure remain absent. | +| `compress.py` | **partial** | `scripts/src/services/profiles/compression.ts`
`scripts/src/services/profiles/compression.test.ts` | A deterministic BFS clustering service emits summary and full IR pages, but there is no Draw.io-facing action, exact loss-aware detail-file workflow, label-propagation parity, or member-cell drill-down target contract. | +| `dbxicons.py` | **optional-deferred** | `scripts/src/services/shape-catalog/shape-catalog.ts`
clean-room 42-tool mapping audit | No licensed Databricks manifest, aliases, variants, pinned-ref embedding, refresh operation, host allowlist, or CLI action was delivered. | +| `diagram_ir.py` | **partial** | `scripts/src/model/diagram-ir.ts`
`scripts/src/services/semantic-lifecycle/import-drawio.ts`
`scripts/src/services/semantic-lifecycle/analysis.ts`
`scripts/src/services/semantic-lifecycle/sync.ts`
`scripts/src/services/semantic-lifecycle/publishing.ts` | Versioned IR, loss-aware import, views, query, policies, failure impact, sync, and story publishing exist, but articulation analysis, a unified architecture-review contract, contrast analysis, multilingual labeling, and explicit peer-IR-v1 compatibility are incomplete. | +| `diagramctl.py` | **partial** | `scripts/src/cli/commands.ts`
`scripts/src/cli/semantic-lifecycle.test.ts`
`scripts/src/actions/doctor/action.ts`
`scripts/src/actions/sync/action.ts` | Lifecycle actions are registered in the existing --action CLI, but integrated importer, profile, transform, and reverse-export services are not registered. There is no uniform peer-equivalent result envelope. | +| `diagramctl_mcp.py` | **optional-deferred** | `scripts/src/cli/commands.ts`
clean-room 42-tool mapping audit | No optional MCP package, JSON-RPC initialization, tools/list, tools/call bridge, closed schemas, timeout handling, or MCP entrypoint exists. | +| `dockerimports.py` | **optional-deferred** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | The importer registry has Docker Compose but no Docker inspect snapshot kind, container/network/volume instance normalization, redaction contract, stdin parity, or action. | +| `drawio2mermaid.py` | **partial** | `scripts/src/services/transforms/reverse.ts`
`scripts/src/services/transforms/reverse.test.ts`
`scripts/src/services/semantic-lifecycle/import-drawio.ts` | A deterministic IR-to-Mermaid service exists, but there is no Draw.io-to-Mermaid CLI/action, shape-form mapping, direction/fence controls, or lossy-conversion report. | +| `drawio2pptx.py` | **optional-deferred** | `scripts/src/cli/commands.ts`
clean-room 42-tool mapping audit | No optional Draw.io renderer adapter, per-page raster loop, PPTX writer, slide sizing, scale option, or structured unavailable result exists. | +| `drawiodiff.py` | **partial** | `scripts/src/services/transforms/semantic-diff.ts`
`scripts/src/services/transforms/semantic-diff.test.ts`
`scripts/src/services/semantic-lifecycle/import-drawio.ts` | The IR service classifies added, removed, changed, moved, and rerouted entities, but no CLI/action composes Draw.io import with diffing, no by-label ambiguity mode exists, and no color-coded graph output or summary diagram is emitted. | +| `drawiohtml.py` | **optional-deferred** | `scripts/src/services/semantic-lifecycle/publishing.ts`
`scripts/src/actions/story/action.ts` | Story HTML is a different semantic publisher; there is no page-to-SVG export adapter, SVG sanitizer, tabbed viewer, pan/zoom/search UI, drill-down link rewrite, or publish-viewer action. | +| `edgeports.py` | **rejected** | `scripts/src/services/authoring-router/orthogonal-router.ts`
`scripts/src/services/authoring-router/orthogonal-router.test.ts`
clean-room 42-tool mapping audit | Only routing during authoring exists. The post-import boundary-port editor, pinned-port preservation, dry-run, idempotence, and transactional Draw.io write path were not selected for this post-phase implementation. | +| `encode_drawio_url.py` | **optional-deferred** | `scripts/src/cli/commands.ts`
`scripts/package.json` | Compression primitives are available transitively, but there is no byte-compatible URL encoder, viewer/edit modes, size policy, privacy warning, or CLI action. | +| `explain.py` | **partial** | `scripts/src/services/transforms/reverse.ts`
`scripts/src/services/transforms/reverse.test.ts` | Structured Markdown for IR pages, nodes, and flows exists as a service, but no Draw.io-facing explain action, tier/type inference, C4 context, unknown-section reporting, or output-file contract is exposed. | +| `goimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | Bounded Go import extraction exists, but it emits imported paths as library nodes rather than resolving only intra-module packages; module discovery, grouping, transitive reduction, and CLI exposure are absent. | +| `heatmap.py` | **partial** | `scripts/src/services/transforms/heatmap.ts`
`scripts/src/services/transforms/heatmap.test.ts` | The IR service validates bounded metrics and applies deterministic accessible colors with legend metadata, but it lacks CSV/JSON loading, label matching, geometry scaling, a rendered legend node, Draw.io transactional output, and CLI exposure. | +| `jsimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | A bounded scanner handles static import/export and require while avoiding tested comments and strings, but dynamic string imports, project module resolution, external exclusion, directory grouping, transitive reduction, and CLI exposure remain incomplete. | +| `k8simports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | Local object/YAML parsing, namespace-qualified identity, Service selectors, Secret references, and Secret payload redaction are tested. Ingress, ConfigMap, PVC, HPA, list-wrapper normalization, ambiguity diagnostics, icon suppression/grouping, stdin action parity, and CLI registration remain absent. | +| `openapiimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | OpenAPI operations and local component-schema references are imported through a service API, but Swagger 2 definitions, nested schema-to-schema edges, method styling, tag groups, no-schema projection, version diagnostics, and CLI exposure are missing. | +| `prdiff.py` | **optional-deferred** | `scripts/src/services/transforms/semantic-diff.ts`
`scripts/src/cli/commands.ts` | Semantic IR diff alone does not provide scoped git revision discovery, A/M/D classification, safe extraction, Draw.io rendering, artifact naming, Markdown reporting, or unavailable-render handling. | +| `pyclasses.py` | **rejected** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | The Python importer extracts imports only. Class declarations, inheritance resolution, multiple inheritance, nested module grouping, ambiguity diagnostics, and transitive reduction were not implemented or registered. | +| `pyimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | Bounded import/from extraction and dynamic-import diagnostics exist, but relative and absolute intra-project resolution, stdlib/third-party exclusion, package grouping, transitive reduction, syntax-error diagnostics, and CLI exposure are absent. | +| `raster2drawio.py` | **partial** | `scripts/src/actions/build/action.ts`
`scripts/src/authoring/ir-to-drawio.ts`
`scripts/src/services/layout/layout-engine.ts`
`scripts/src/model/diagram-ir.ts` | Generic IR build supports explicit geometry, styles, edges, and automatic layout, but there is no raster-extracted graph compatibility schema/action, x/y/w/h shorthand conversion, partial-coordinate policy, confidence/provenance convention, or extraction-warning envelope. | +| `relabel.py` | **partial** | `scripts/src/services/transforms/relabel.ts`
`scripts/src/services/transforms/relabel.test.ts` | A strict complete-map IR relabel service preserves non-label structure, but there is no extraction mode, page-name handling, UserObject traversal contract, partial-map/unmatched reporting, Draw.io transactional write, or CLI action. | +| `repair_png.py` | **optional-deferred** | `scripts/src/cli/commands.ts`
clean-room 42-tool mapping audit | No PNG chunk validator, signature-specific repair, atomic in-place replacement, idempotence gate, version gate, or optional action exists. | +| `restyle.py` | **partial** | `scripts/src/services/themes/theme-service.ts`
`scripts/src/services/themes/theme-service.test.ts` | Five validated built-in themes and immutable IR application exist, but the peer-style palette-slot schema, user preset loader, hue/neutral color remapping, global extras, versioned JSON schema, Draw.io transactional action, and CLI exposure are incomplete. | +| `runbook.py` | **partial** | `scripts/src/services/profiles/runbook.ts`
`scripts/src/services/profiles/runbook.test.ts` | The service emits escaped self-contained interactive HTML from an explicit RunbookGraph, but it does not parse Draw.io, infer node types/start nodes/choices, report fallback selection, or expose a publish-runbook action. | +| `rustimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | A bounded subset recognizes mod and simple use roots and diagnoses macros, but crate/self/super resolution, module-file discovery, complete brace expansion, external-crate exclusion, grouping, reduction, and CLI exposure are absent. | +| `seqlayout.py` | **partial** | `scripts/src/services/profiles/sequence.ts`
`scripts/src/services/profiles/sequence.test.ts` | Participants, ordered messages, lifelines, activations, return validation, and editable geometry are implemented as a service, but notes are unsupported and no sequence schema file, input action, direction/options contract, or CLI registration exists. | +| `shapesearch.py` | **partial** | `scripts/src/services/shape-catalog/shape-catalog.ts`
`scripts/src/services/shape-catalog/shape-catalog.test.ts` | Deterministic exact/alias/fuzzy search exists for eight hand-curated generic shapes, not the licensed 10k+ palette index; compound/tag/Soundex ranking, dimensions, gzip integrity controls, expected ecosystem queries, and CLI output are missing. | +| `sqlerd.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | A narrow line-oriented subset finds simple tables and REFERENCES edges, but columns/types, PK/FK markers, quoted/schema identifiers, composite keys, schema grouping, crow's-foot styles, unsupported-syntax diagnostics, and CLI exposure are missing. | +| `svgflow.py` | **optional-deferred** | `scripts/src/cli/commands.ts`
clean-room 42-tool mapping audit | No optional Draw.io SVG export adapter, SVG parser/sanitizer, connector detection, animation injection, reduced-motion handling, or export-flow-svg action exists. | +| `tfimports.py` | **partial** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | A bounded line-oriented resource/reference subset exists, but modules, multiline/nested HCL handling, comments/string false-positive guarantees, diagnostics for dynamic expressions, cloud styles, grouping, transitive reduction, no-icons mode, and CLI exposure are incomplete. | +| `tfstate.py` | **optional-deferred** | `scripts/src/services/source-importers/index.ts`
`scripts/src/services/source-importers/index.test.ts` | No Terraform show-JSON snapshot source kind, nested module traversal, count/for_each instance expansion, sensitive-value redaction, state relationship extraction, stdin parity, or optional action exists. | +| `timelapse.py` | **partial** | `scripts/src/services/profiles/timelapse.ts`
`scripts/src/services/profiles/timelapse.test.ts` | The service classifies changes across caller-supplied IR snapshots, but it has no scoped git history/archive adapter, deterministic commit sampling, importer allowlist, Draw.io frame rendering, HTML player, resource limits, or CLI action. | +| `tubemap.py` | **partial** | `scripts/src/services/profiles/tube-map.ts`
`scripts/src/services/profiles/tube-map.test.ts` | The native service provides deterministic grid-aligned octilinear routes, interchange semantics, validation, and tested obstacle avoidance, but no versioned input schema, build-tubemap action, file adapter, or CLI exposure exists. | +| `validate.py` | **partial** | `scripts/src/actions/validate/action.ts`
`scripts/src/actions/quality/action.ts`
`scripts/src/actions/page-connectors-validation/action.ts`
`scripts/src/actions/page-shape-bbox-validation/action.ts`
`scripts/src/actions/page-orphans/action.ts` | Structural compilation and several specialized quality checks exist, but findings remain fragmented rather than one stable code/severity/subject/fix schema; duplicate/reserved ID, parent, off-grid, strict-warning, JSON projection, and comparable readability-score acceptance coverage is incomplete. | + +## Architectural boundary + +The retained implementation stays in the existing TypeScript/Node.js stack with pnpm, Taskfile, `@maxgraph/core`, and the established action-based CLI. Python, Graphviz, Eclipse Layout Kernel (ELK), Model Context Protocol (MCP), browser services, network icon retrieval, and Draw.io Desktop are not mandatory dependencies. Optional adapters must report availability honestly. + +## Delivery note + +This matrix describes the combined integrated candidate and deliberate scope decisions. Gitea publication and Hermes runtime installation are separate gates and must not be inferred from this document. \ No newline at end of file diff --git a/references/capabilities.md b/references/capabilities.md index a9abb21..1730259 100644 --- a/references/capabilities.md +++ b/references/capabilities.md @@ -99,3 +99,16 @@ Always prints YAML to stdout. Exit code `0` on success, `1` on error. | `page-recommendations` | Page 0 | Smallest standard page size (A4→A3→A2→A1→custom) that fits content with 80 px margin | > For install/build instructions, source structure, and how to add new actions, see [maintenance.md](./maintenance.md). + +--- + +## Capability 5 — Native service libraries + +The package includes additional strict TypeScript APIs under `scripts/src/services/`: + +- `source-importers/` — conservative, bounded source/configuration topology extraction with diagnostics and no code execution; +- `themes/` and `shape-catalog/` — five validated themes and an offline generic shape catalog; +- `transforms/` — reverse Mermaid/Markdown, semantic diff, complete-map relabeling, and accessible bounded heatmaps; +- `profiles/` — C4, sequence, tube map, compression, runbook, timelapse, and build-up profiles. + +These services are covered by the native test suite but are not registered CLI actions. Their exact peer-relative coverage and deliberate omissions are listed in [agents365-capability-coverage.md](./agents365-capability-coverage.md).