Integrate the Monaco editor to edit `CustomTools` and others in Reshapr UI

[lbroudoux]

As of today, the Reshapr UI just offers a raw visualization of artifacts. We could do better! We could also allow creating and editing/updating them via the UI.

The idea here is to include the Monaco editor with support for YAML syntax to allow the edition of our different custom artifacts. Thanks to the support of completion and the JSON schemas we have for every spec, it should be fairly easy to have a nice editing experience with contextual help and so on.

We could put this into the Artifacts thumb within a service details page. Having this page allows us to list, create and update existing artifacts. Upon creation, we could just ask the kind of artifact to create and then make the Monaco editor point to the correct JSON Schema to offer contextual help and auto-completion.

[gozen59]

It's a great idea.
I purpose this plan with several. What do you think ?

Overview

Add a Monaco YAML editor with JSON Schema completion on the Artifacts tab of the service details page, to list, create, and update the 4 Reshapr custom artifact types — delivered in small, reviewable increments, with no new backend endpoint (reuse POST /attach).

Current state

Item	Status
Artifacts tab	web-ui/src/routes/(app)/services/[id]/artifacts/+page.svelte — raw JSON dump via JsonBlock
Creation	Experimental page /artifacts — file upload only
Update API	No PUT/PATCH — but attachArtifactFile replaces the existing artifact of the same type (ServiceManagerService.java, lines 279–287)
JSON Schemas	4 files in control-plane/src/main/resources/schemas/
Monaco	Not in web-ui/package.json

v1 scope: only the 4 custom kinds (Prompts, CustomTools, Resources, ToolsOutputFilters). The main spec (OpenAPI, GraphQL, Protobuf, etc.) remains read-only in the list.

Target architecture

flowchart TB
  subgraph ui [web-ui]
    ListPage["ArtifactListTable"]
    RoutePage["route mince artifactId"]
    Editor["CustomArtifactEditor.svelte"]
    Monaco["YamlMonacoEditor.svelte"]
    Lib["lib/artifacts/*"]
    ListPage --> RoutePage
    RoutePage --> Editor
    Editor --> Monaco
    Lib --> Editor
    Lib --> Monaco
  end

  subgraph api [control-plane via BFF]
    Refs["GET /artifacts/service/id/refs"]
    Get["GET /artifacts/id"]
    Attach["POST /artifacts/attach"]
  end

  ListPage --> Refs
  RoutePage --> Get
  Editor -->|"saveCustomArtifact"| Attach
  Monaco --> StaticSchemas["static/schemas/*.json"]

Loading

Factorization — layered architecture

The component should be factorized. Without it, Increments 4/5 would duplicate ~80% of the code (Monaco, schema, validation, save, toolbar, errors). The existing UI already duplicates YAML display via Collapsible + ScrollableCode on 4 MCP pages.

Layer 1 — YamlMonacoEditor.svelte (pure presentation)

Client-only Monaco wrapper, no artifact business logic.

• Props: value, readOnly, schemaUri, height, onChange, onValidationChange
• Single responsibility: Monaco init, Vite workers, monaco-yaml config, error markers
• Reusable anywhere Reshapr YAML is displayed or edited

Layer 2 — YamlArtifactPanel.svelte (reusable display)

Replaces the repeated Collapsible + ScrollableCode pattern on MCP pages.

• Props: title, yaml, schemaUri?, defaultOpen?, editHref?
• Read-only mode: delegates to YamlMonacoEditor (lazy-load) or falls back to ScrollableCode
• Used in Increment 5 (optional) on MCP pages

Layer 3 — CustomArtifactEditor.svelte (create/edit/view logic)

Single business component — core of the factorization.

• Prop mode: 'create' | 'edit' | 'view'
• Prop kind (create, via query ?kind=Prompts) or artifact (edit/view, loaded by the route)
• Contains: kind selector (create only), Edit/Cancel/Save toolbar, ApiErrorAlert, unsaved changes guard
• Delegates editing to YamlMonacoEditor
• Single implementation of the save flow

Layer 4 — lib/artifacts/ module (shared, testable logic)

File	Role
types.ts	ArtifactRef, ArtifactDetail, ReshaprArtifactKind, EditorMode
kinds.ts	Registry: kind → ArtifactType, label, schemaPath, isEditable
templates.ts	buildTemplate(kind, service) — YAML templates
attach.ts	yamlToAttachFile(content, kind), saveCustomArtifact(client, content, kind)
parse.ts	extractKindFromYaml(content) — infer kind in edit mode

The SvelteKit route stays thin (~30 lines): resolves mode, loads data, then renders <CustomArtifactEditor />.

Single route

/services/[id]/artifacts/[artifactId]/+page.svelte

• artifactId === 'new' + ?kind=Prompts → mode: 'create'
• artifactId UUID + editable type → mode: 'view' (Edit button → edit)
• artifactId UUID + non-custom type → mode: 'view' permanently read-only

Extracted list component

ArtifactListTable.svelte — reusable table (columns, read-only badges, View/Edit/Create actions).

Breakdown into small Increments

Increment 1 — API foundations + structured list

Goal: replace raw JSON with a navigable list; scaffold the lib/artifacts/ module without Monaco.

• web-ui/src/lib/api/client.ts — add listArtifactRefsByService, getArtifact
• Create web-ui/src/lib/artifacts/: types.ts, kinds.ts, templates.ts, attach.ts, parse.ts
• New ArtifactListTable.svelte
• Refactor artifacts/+page.svelte: call /refs, table, New custom artifact button → /artifacts/new?kind=Prompts

Reviewable PR: ~200 lines, no new dependencies.

Increment 2 — YamlMonacoEditor (presentation layer)

Goal: SSR-safe Monaco integration; reusable component with no business logic.

Dependencies: monaco-editor, monaco-yaml

• New YamlMonacoEditor.svelte (dynamic import, Vite workers)
• Thin route [artifactId]/+page.svelte — read-only integration proof

Reviewable PR: isolated component + skeleton route.

Increment 3 — JSON Schemas + contextual completion

Goal: auto-completion, inline validation — in YamlMonacoEditor only.

• web-ui/scripts/copy-schemas.mjs (prebuild) — copy from control-plane/src/main/resources/schemas/
• monaco-yaml config via schemaUri prop (resolved from kinds.ts)
• onValidationChange bubbles errors to the parent

Increment 4 — Unified CustomArtifactEditor (create + edit + view)

Goal: a single component and a single route to create, view, and edit.

Mode	Entry	Behavior
create	/artifacts/new?kind=Prompts	Kind selector, template, edit, save
view	/artifacts/{id}	Monaco read-only, Edit button if custom type
edit	toggle from view	Editable Monaco, Cancel/Save, unsaved guard

Safeguards: block save on validation errors; server errors via ApiErrorAlert; beforeNavigate for unsaved changes.

Increment 5 — Polish and MCP reuse (optional)

• YamlArtifactPanel.svelte on 4 MCP pages
• "Edit in Artifacts" links from mcp-prompts / mcp-custom-tools
• Artifact count on Overview
• Manual tests documented in the PR

Key technical points

No backend required for v1 — POST /api/v1/artifacts/attach covers both creation and update (replace by type).

SSR and bundle size — Monaco ~2–3 MB: client-only dynamic import, limit to artifact routes, consider vite-plugin-monaco-editor if needed.

Two-level validation:

1. Client: monaco-yaml + JSON Schema
2. Server: ReshaprArtifactBuilder on attach (source of truth)

Creation template (example Prompts):

apiVersion: reshapr.io/v1alpha1
kind: Prompts
service:
  name: {{service.name}}
  version: {{service.version}}
prompts: {}

Out of scope for v1: Experimental /artifacts page (main spec import); ScrollableCode kept as lightweight fallback.

Recommended merge order

Increment 1 → Increment 2 → Increment 3 → Increment 4 → Increment 5 (optional)

Acceptance criteria

• Artifact list on service page (types, main/custom, actions)
• Create a custom artifact with kind selection
• YAML editing with syntax highlighting, auto-completion, and schema errors
• Save via attach, transparent replacement by type
• Main spec visible but not editable
• No regression on Experimental /artifacts page

[lbroudoux]

This looks like a decent and logical breakdown. I wonder, though, why you'd consider SSR... as of today, everything is client-side rendered as far as I know. Why introduce SSR on this specific use-case?
Also, take care of the number of pages it will be included... It says 4 pages but I think it would be more logical to have a single Artifacts page and to be able to list/filter/pick and create by selecting the type or artifact (Prompt, Resource, CustomTools and ToolsOuputFilter as of today).

[gozen59]

On SSR

Good catch — we're not introducing SSR on this feature. The plan wording was misleading.
The web-ui already runs as a SPA (export const ssr = false in +layout.ts). Monaco would not be server-rendered today, and we're not changing that.
What we actually meant: don't top-level import 'monaco-editor' because it's a browser-only library (window, web workers). Dynamic import in onMount is the right pattern here — not because we're enabling SSR, but because Monaco doesn't run outside the browser.
We'll update the plan to say client-only Monaco integration (dynamic import, Vite worker config, no change to global ssr = false).

On a single Artifacts page

Good point — we agree.
The plan targets a single Artifacts page per service as the entry point to list, filter, pick, and create/edit custom artifacts. Releases 1–4 are centered there: structured list, type filter, kind selection on create, editing via one CustomArtifactEditor.
The mention of "4 pages" in optional release 5 was poorly worded: it referred to existing MCP pages that already display YAML read-only — not 4 separate editor entry points. That's not the approach we want.
Updated plan:

• Artifacts = single hub (list + filter by type + create by kind selection + Monaco editor)
• MCP tabs = resolved views (tools/prompts as consumed by the gateway), with optional "Edit in Artifacts" links — no second YAML editor
• Release 5 simplified or dropped; no duplicated Monaco on MCP pages

---

Thanks for the feedback — we'll make this explicit in the plan.