feat(models): add full JSON model export/import workflow with UI support

[krystianbajno]

JSON Import/Export Feature

Goal Delivered

Implemented full model JSON transfer so a Gram model can be:

• exported to JSON,
• edited externally (including AI-assisted edits),
• imported back into Gram in a safe, validated way.

This includes backend APIs, core transfer logic, frontend UI actions, auth/authz enforcement, and test coverage.

What Is New

1) Versioned JSON Transfer Contract

Introduced a dedicated contract for model transfer:

• core/src/data/models/ModelTransfer.ts

Key additions:

• MODEL_TRANSFER_SCHEMA_VERSION
• ModelExportPayload with full model-bound data:
  • metadata
  • model
  • modelData (components, dataFlows)
  • threats, controls, mitigations
  • suggestions (now exported empty intentionally)
  • links, flows, resourceMatchings, review
• ImportMode: create-new and in-place
• ModelImportOptions and ModelImportResult

AI-friendly metadata support:

• metadata.aiInstructions is exported for deterministic external editing guidance.

2) Core Transfer Service (Export + Import)

Created/extended transfer orchestration in:

• core/src/data/models/ModelTransferService.ts

Export behavior:

• Assembles full payload for a model and related entities.
• Exports suggestions as empty arrays.
• Exports threat.suggestionId and control.suggestionId as unset to avoid stale/fake bindings.

Import behavior:

• Validates payload and references.
• Supports two modes:
  • create-new: imports into a newly created model.
  • in-place: replaces target model content.
• Runs transactionally.
• Regenerates IDs and remaps relationships (components, data flows, threats, controls, links, flows, mitigations).
• Handles optional/nullable fields from real data safely.
• Defaults missing dataFlow.bidirectional to false for compatibility with older payloads.

DAL wiring:

• core/src/data/dal.ts now exposes modelTransferService.

3) Backend API Endpoints

Added model JSON transfer endpoints under v1 models router:

• GET /api/v1/models/:id/export-json
• POST /api/v1/models/import-json

Files:

• api/src/resources/gram/v1/models/exportJson.ts
• api/src/resources/gram/v1/models/importJson.ts
• api/src/resources/gram/v1/models/router.ts

Validation:

• Added Zod schema for transfer payload:
  • api/src/resources/gram/v1/models/jsonTransferSchema.ts
• Includes compatibility for nullable/optional fields (severity, description, reason, shouldReviewActionItems, bidirectional).

Security:

• Endpoints enforce existing authentication/authorization model.
• Import endpoint includes payload size guard (413 on oversized payloads).

4) Frontend Buttons + Modals

Added user-facing import/export actions in model board UI.

API integration:

• app/src/api/gram/model.js
  • exportModelJson query
  • importModelJson mutation

Modals:

• app/src/components/model/modals/ExportModelJson.js
• app/src/components/model/modals/ImportModelJson.js

Modal registration:

• app/src/components/elements/modal/ModalManager.js

Toolbar buttons:

• app/src/components/model/board/components/ControlsToolBar.js
  • Export full model JSON button
  • Import model JSON button
  • Permission-aware enable/disable behavior

5) Tests

Added endpoint-level tests for JSON transfer:

• api/src/resources/gram/v1/models/jsonTransfer.spec.ts

Coverage includes:

• auth/authz behavior
• create-new import mode
• in-place import mode
• relationship integrity and transfer behavior

Build Status

Validated after changes:

• @gram/core build passes
• @gram/api build passes
• @gram/config build passes

Practical Usage

1. Open a model in UI.
2. Use toolbar export button to download JSON.
3. Edit JSON externally (manual or AI-assisted).
4. Use import modal:
   • create-new to create a new model from JSON.
   • in-place to overwrite current model content.

Notes

• Exported suggestions are intentionally excluded to avoid stale/fake suggestion artifacts in transfer payloads.
• IDs are regenerated on import; references are remapped automatically.
• Payload remains schema-versioned and suitable for round-trip workflows.