diff --git a/analysis/uml/nn.vpp b/analysis/uml/nn.vpp index 5f37537f..0efc6c9f 100644 Binary files a/analysis/uml/nn.vpp and b/analysis/uml/nn.vpp differ diff --git a/docs/knowledge/architecture/browser-mcp.md b/docs/knowledge/architecture/browser-mcp.md index 1c91e8bd..a39bf1b2 100644 --- a/docs/knowledge/architecture/browser-mcp.md +++ b/docs/knowledge/architecture/browser-mcp.md @@ -1,7 +1,7 @@ --- kind: knowledge status: current -updated: 2026-08-30 +updated: 2026-09-14 --- # Browser-backed MCP architecture @@ -116,6 +116,16 @@ counterparts use the distinct routes above. | Format view | `FlowCanvas` calls `diagram.autoLayout` for horizontal/vertical **Disponi**. No MCP tool or browser RPC case exposes it. `fit_view`, `center_view` and `move_nodes` are not equivalent. | | Screenshot | CDP capture supports optional reload and output-handle hover. It neither performs layout nor waits for the editor's layout/render completion, so it does not enforce the required layout-before-capture workflow. | | Open a project | MCP exposes `create_project({projectPath,id,version,name,description})` and `open_project({projectPath})` through a confined `NNM_PROJECT_ROOT`; the server prepares/loads bytes and the browser bridge owns activation and model-save notifications. A live browser tab is still required before activation; `import_diagram`/`reset_diagram` remain distinct operations. | +| Create stereotype | `create_stereotype` validates the complete JSON form shape at MCP, then delegates the unchanged semantic request to the selected browser's shared project-authoring service and stereotype coordinator. The browser writes, stages and activates the project package. | +| Delete stereotype | `delete_stereotype({id,version,path})` delegates exact ownership, graph-use and dependency checks to the shared browser coordinator. The UI uses the same operation with confirmation; core, missing, in-use and dependency-required packages are rejected without cascade. | +| Create dataset | `create_dataset` exposes the complete dataset form shape. Optional file bytes use canonical base64 only across JSON and are decoded before the shared browser dataset coordinator validates and writes them. | +| Delete dataset | `delete_dataset({id,version,path})` delegates to the same coordinator as the UI. It removes the project manifest/directory/catalog/training descriptor while preserving backend archives and historical jobs. | + +The four authoring operations are serialized by the browser-owned project +authoring service. Package-scope transitions temporarily suppress the visible +catalog and reject package-node additions until the runtime commit or rollback +finishes, so asynchronous create/delete/import work cannot reintroduce an +identity absent from the committed project scope. ### Implementation evidence diff --git a/docs/knowledge/decisions/project-workspaces-and-stereotype-authoring.md b/docs/knowledge/decisions/project-workspaces-and-stereotype-authoring.md index 27eaec32..0d257a82 100644 --- a/docs/knowledge/decisions/project-workspaces-and-stereotype-authoring.md +++ b/docs/knowledge/decisions/project-workspaces-and-stereotype-authoring.md @@ -1,7 +1,7 @@ --- kind: decision status: accepted -updated: 2026-09-10 +updated: 2026-09-14 --- # Writable project workspaces and model-owned stereotype authoring @@ -58,6 +58,18 @@ the user can edit the Lua and PyTorch implementations outside NNModelling. `inference.lua`, and `pytorch.py`, adds the exact relative entry to the model's `manifest.customPackages`, stages the resulting package scope, and exposes the stereotype in the current palette. +- An exact project-owned stereotype may be deleted from the visible manager or +through browser-backed MCP. Core packages are immutable. Deletion is rejected +when the graph uses the exact package identity or another project-owned package +resolves it as a dependency; the operation never cascades into nodes or rewrites +dependencies. The editor runtime resolves dependency ranges against the complete +model scope while loading project package records and exposes those exact keys +through `packageExports()` for the shared UI/MCP deletion guard. +- Successful deletion removes the exact `manifest.customPackages` entry, + project-relative package directory and active runtime/catalog entry. The next + scope is staged before commit. On write, removal or activation failure, the + previous manifest, package bytes and runtime scope are restored; unrelated + project resources are never removed. - Generation is transactional from the application's perspective: validate all content and the staged package scope before committing it; on a later filesystem or activation failure, restore the previous model and remove only @@ -85,6 +97,9 @@ the user can edit the Lua and PyTorch implementations outside NNModelling. automatic saving. - Project creation, opening, graph editing, package authoring, and backend export all operate on the same `core + current-model-custom` package scope. +- UI and browser-backed MCP creation/deletion call the same project authoring + coordinators. The MCP boundary adapts JSON transport but does not own a second + generator, package catalog or filesystem model. - Direct edits made by another application are not watched automatically. Reloading a project or an explicit future refresh action is the boundary for rereading those files. @@ -100,5 +115,8 @@ the user can edit the Lua and PyTorch implementations outside NNModelling. ## Implementation -The executable work is defined in +The base workspace and authoring work is defined in [`../../plans/active/project-workspaces-and-stereotype-authoring/plan.md`](../../plans/active/project-workspaces-and-stereotype-authoring/plan.md). +UI/MCP creation and deletion parity is tracked by the +[`../../plans/active/mcp-project-authoring-parity/plan.md`](../../plans/active/mcp-project-authoring-parity/plan.md) +initiative. diff --git a/docs/knowledge/uml/mcp-use-case-parity.md b/docs/knowledge/uml/mcp-use-case-parity.md index 4462c64e..1b11034e 100644 --- a/docs/knowledge/uml/mcp-use-case-parity.md +++ b/docs/knowledge/uml/mcp-use-case-parity.md @@ -1,21 +1,22 @@ --- kind: decision status: accepted -updated: 2026-08-30 +updated: 2026-09-14 --- # MCP use-case parity with the editor ## Context and authority -The MCP interface must expose the agent-facing modeling and training workflows -below, not merely a collection of low-level graph and HTTP operations. This is +The MCP interface must expose the agent-facing modeling, project-authoring and +training workflows below, not merely a collection of low-level graph and HTTP operations. This is an accepted functional constraint, not a claim that the server already implements it. The [browser-backed MCP architecture](../architecture/browser-mcp.md) describes actual implementation and gaps separately. The -[adaptation plan](../../plans/active/mcp-use-case-parity/plan.md) maps these -requirements to implementation tasks and verification gates; its existence does -not mean the server already satisfies this constraint. +[adaptation plan](../../plans/active/mcp-use-case-parity/plan.md) and the +[project-authoring parity plan](../../plans/active/mcp-project-authoring-parity/plan.md) +map these requirements to implementation tasks and verification gates; their +existence does not mean the server already satisfies this constraint. The diagram preserves the user-supplied use cases, associations, extension and notes. `Agent` is the single primary actor. The two groups are capability areas, @@ -31,21 +32,25 @@ flowchart LR subgraph TRAINING["Training"] direction TB - T1(["Collegarsi al backend"]) - T2(["Modificare parametri"]) - T3(["Lanciare training"]) - T4(["Monitoraggio training"]) + T1(["Connect to backend"]) + T2(["Edit training parameters"]) + T3(["Start training"]) + T4(["Monitor training"]) T5(["Download wheel"]) end - subgraph MODELLAZIONE["Modellazione"] + subgraph MODELING["Modeling"] direction TB - M1(["Aggiungere nodo al canvas"]) - M2(["Collegare nodi"]) - M3(["Modificare parametri nodi"]) - M4(["Formattare la vista"]) - M5(["Screenshot
─────────────
extension points
Formattare la vista"]) - M6(["Aprire un progetto"]) + M1(["Add node to canvas"]) + M2(["Connect nodes"]) + M3(["Edit node parameters"]) + M4(["Format view"]) + M5(["Screenshot
─────────────
extension points
Format view"]) + M6(["Open a project"]) + M7(["Create stereotype"]) + M8(["Delete stereotype"]) + M9(["Create dataset"]) + M10(["Delete dataset"]) M4 -. "«extend»" .-> M5 end @@ -62,19 +67,28 @@ flowchart LR A --- M4 A --- M5 A --- M6 + A --- M7 + A --- M8 + A --- M9 + A --- M10 N1["«note»
Every training parameter shown in the sidebar
must be editable through MCP."] N2["«note»
Create a node by filling in its stereotype parameters.
Creation must behave exactly like selecting the stereotype
in the browser sidebar and clicking Create."] - N3["«note»
Use the editor's Arrange (Disponi) operation
to place nodes in a standard layout.
Run it BEFORE capturing the browser screenshot.
Support both horizontal and vertical layouts."] + N3["«note»
Use the editor's Arrange operation
to place nodes in a standard layout.
Run it BEFORE capturing the browser screenshot.
Support both horizontal and vertical layouts."] N4["«note»
The MCP server must create a new project
or open an existing one.
Project creation must use the same parameters and behavior
as the graphical interface, sharing as much code as possible."] + N5["«note»
MCP stereotype and dataset creation uses the same semantic
parameters, validation, defaults and project transaction as the UI.
Deletion is available in both UI and MCP and removes only project-owned resources."] T2 -.- N1 M1 -.- N2 M4 -.- N3 M6 -.- N4 + M7 -.- N5 + M8 -.- N5 + M9 -.- N5 + M10 -.- N5 ``` ## Required observable behavior @@ -92,6 +106,18 @@ flowchart LR | M4 | Format view | Apply the editor's **Disponi** auto-layout in either horizontal or vertical direction. Panning, zooming, fitting the viewport, or manually guessing node coordinates are not equivalent. | | M5 | Screenshot | Capture the browser diagram after the required layout has been applied and rendered. | | M6 | Open a project | Create a new project or open an existing one through the browser's shared project workflow. Creation exposes the same form parameters, defaults, validation and behavior as the UI; opening activates the same writable project and resource scope. | +| M7 | Create stereotype | Create one project-owned stereotype with the UI form's complete semantic request: identity, directory, display metadata, kind, view, dependencies, parameter definitions and optional objective metadata. The shared browser transaction writes and activates the package. | +| M8 | Delete stereotype | Delete only an exact project-owned stereotype through a UI confirmation or MCP request. Reject core, missing, graph-used or dependency-required packages. Success removes the exact manifest entry, project directory, active catalog/runtime entry and palette entry without deleting nodes or cascading to other packages. | +| M9 | Create dataset | Create one project-owned dataset with the UI form's complete semantic request: identity, directory, display metadata, parameter definitions, named input/target slots, class metadata and optional data files. Binary file transport may be adapted to JSON-safe base64 without changing domain semantics. | +| M10 | Delete dataset | Delete only an exact project-owned dataset through a UI confirmation or MCP request. Success removes its manifest entry, exact project directory, browser catalog entry and active training descriptor; immutable backend uploads and historical jobs are preserved. | + +Creation and deletion are project authoring operations, not graph-node creation +or backend archive administration. Both entry points must call the same +browser-owned coordinators. Destructive calls identify the exact project +resource by ID, version and relative path; display names are never identities. +Failures preserve the previous manifest, runtime/catalog state and unrelated +files. No deletion operation may cascade into graph nodes, dependent packages, +backend dataset archives or historical jobs. The original `«extend»` relation is retained faithfully. Its note explicitly requires layout **before** screenshot; this ordering is the acceptance rule, diff --git a/docs/plans/active/mcp-project-authoring-parity/evidence/T05-final-qa.md b/docs/plans/active/mcp-project-authoring-parity/evidence/T05-final-qa.md new file mode 100644 index 00000000..8ece2b9e --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/evidence/T05-final-qa.md @@ -0,0 +1,34 @@ +# T05 final QA evidence + +**Run date:** 2026-09-14 +**Result:** PASS — automated gates and disposable live UI/MCP QA passed. + +## Automated gates + +| Gate | Result | Evidence | +| --- | --- | --- | +| `pnpm --dir front-end check` | Pass | 0 errors; 35 warnings across 8 files. | +| `pnpm --dir front-end test` | Pass | 50 files; 302 tests passed. | +| `pnpm --dir front-end guard:package-only` | Pass | `package-only guard: ok` with the current `data.package` identity contract (`id` and `version`). | +| `pnpm --dir mcp-server test` | Pass | TypeScript build succeeded; 7 files and 74 tests passed. | +| `git diff --check` | Pass | No whitespace errors. | + +The implementation owner also reported 10/10 focused authoring tests passing. The full frontend suite above was rerun after the final runtime dependency-resolution fix. + +## Disposable live-project QA + +Used a temporary copy of the existing VAE project at `/tmp/nnmodelling-t05-commit-qa`; all live authoring and failure injection targeted this clone. The public MCP registry exposed all four authoring tools. + +- Created semantically equivalent stereotypes through the UI (`qa.ui-layer`) and MCP (`qa.mcp-layer`). Their project folders contained the expected four package files and appeared in the live catalog. +- Created equivalent named-slot datasets through the UI (`qa.ui-dataset`) and MCP (`qa.mcp-dataset`), plus an MCP dataset with `dataFiles`. The manifests, generated source and live catalog reflected the submitted contracts; `data/probe.bin` contained exactly `00 01 02 03 04`. +- Created `qa.guard-target` and `qa.guard-dependent` through MCP. Runtime diagnostics were clear, and deleting the target while required was rejected with “required by another project stereotype” and no mutation. Deleting the dependent then allowed the target deletion. +- Core stereotype deletion and deletion of graph-used `example.vae.sampling@0.1.0` were both rejected without mutation. +- UI cancellation of `qa.mcp-dataset` left it listed and present. Confirmed UI deletion then removed it. UI deletion of `qa.ui-layer` and MCP deletion of `qa.mcp-layer`, `qa.ui-dataset` and the file-backed dataset succeeded through their respective paths. +- Injected an `EACCES` failure by removing write permission from the package parent before deleting `qa.ui-layer` through MCP. The operation failed; SHA-256 hashes of `model.json` and all stereotype files were unchanged, the package remained, and the parent permission was restored. +- Reopened the clone through MCP. The existing VAE graph returned as Saved with `resourceCount: 17`, and no QA resources remained in its project folders or catalogs. + +The earlier live failure of the dependency guard is superseded by this run: the latest runtime resolves dependency ranges against the complete package scope, and the live guard now rejects the dependent deletion before mutation. + +## Cleanup and final state + +Removed the disposable project and rollback snapshots. Stopped the temporary-root MCP server and restarted the local server against the repository's existing `Variational Autoencoder` project (`example.vae-mnist`, `resourceCount: 17`). The original project opened successfully in the in-app editor. `git status --short -- examples/` is empty; no QA changes remain in `examples/` or `transformer.spam`. diff --git a/docs/plans/active/mcp-project-authoring-parity/plan.md b/docs/plans/active/mcp-project-authoring-parity/plan.md new file mode 100644 index 00000000..9c72df5d --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/plan.md @@ -0,0 +1,136 @@ +--- +id: mcp-project-authoring-parity +kind: plan +status: completed +updated: 2026-09-14 +areas: [architecture, frontend, mcp, testing] +--- + +# MCP parity for project stereotype and dataset authoring + +## Goal + +Expose four project-authoring workflows through MCP—create/delete stereotype +and create/delete dataset—with the same semantic parameters, validation, +transactions and live editor effects as the visible frontend. Add stereotype +deletion to the UI and keep dataset deletion on the same shared operation. + +## Delivered behavior + +The frontend and browser-backed MCP expose shared project-scoped operations to +create and delete stereotypes and datasets. The UI and MCP paths use the same +validation, transactions, active package/dataset catalogs and rollback. Exact +project ownership is required for deletion; core, graph-used and +dependency-required stereotypes are protected. T05 final QA passed on +2026-09-14; see [the evidence](evidence/T05-final-qa.md). + +## Scope + +- Shared browser operations for all four use cases. +- UI confirmation and transactional deletion for project stereotypes. +- JSON-safe MCP transport for the frontend forms' complete semantic requests, + including optional dataset data files. +- Exact public schemas, frontend RPC handling, MCP adapters and regression tests. + +## Non-goals + +- Dataset update through MCP, stereotype source-code editing, rename or move. +- Core stereotype deletion, cascading node deletion or dependency rewriting. +- Deleting immutable backend dataset archives or historical jobs. +- A second server-side package catalog, authoring generator or graph owner. + +## Decisions and invariants + +- The accepted behavior is defined in + [MCP use-case parity](../../../knowledge/uml/mcp-use-case-parity.md). +- The active browser project and `DiagramCore` remain authoritative. UI and RPC + call the same project coordinators; MCP performs only schema and transport + adaptation. +- Create payloads preserve the exact semantic fields of + `StereotypeAuthoringRequest` and `DatasetAuthoringRequest`. Dataset bytes use + `{path, dataBase64}` only at the JSON boundary and become `Uint8Array` before + domain validation. +- Delete payloads use exact `{id, version, path}` identity. Only project-owned + resources are eligible. +- Stereotype deletion rejects packages referenced by graph nodes or required by + another active custom package. It never cascades into nodes or dependencies. +- Dataset deletion preserves backend archives and jobs. Both deletions are + transactional and preserve manifest, runtime/catalog state and unrelated + files on failure. +- Create returns the created exact identity. Delete returns the deleted exact + identity. Errors are truthful and do not report partial success. + +## Contracts and control flow + +```text +UI form/confirmation ─┐ + ├─> shared FlowCanvas authoring service +MCP tool -> browser RPC┘ -> project coordinator -> ordered writer + ├─> project directory + └─> live package/dataset scope +``` + +Public operations are `create_stereotype`, `delete_stereotype`, +`create_dataset`, and `delete_dataset`. The MCP server validates their JSON +shape and forwards them to the selected browser tab. Domain defaults, +cross-field validation, package activation, dataset catalog updates and +rollback stay in the frontend. + +## Task graph + +| Task | Role | Depends on | May run with | Write scope | Outcome | +| --- | --- | --- | --- | --- | --- | +| [T01](tasks/T01-contract-and-kb.md) | architecture | — | — | This plan and current KB | Accepted four-operation contract | +| [T02](tasks/T02-frontend-shared-authoring.md) | frontend | T01 | T03 | `front-end/` | Shared UI/RPC CRUD behavior and frontend regressions | +| [T03](tasks/T03-mcp-authoring-tools.md) | integration | T01 | T02 | `mcp-server/` | Four public tools and proxy regressions | +| [T04](tasks/T04-integration-review.md) | review | T02, T03 | — | Read-only; fixes return to owners | Cross-boundary contract review | +| [T05](tasks/T05-final-qa.md) | integration | T04 | — | Disposable fixtures and evidence only | Passed real UI/MCP/filesystem QA | + +## Integration and review gates + +- T02 and T03 use the contract above and have disjoint write scopes. +- T04 checks schema/RPC agreement, shared browser ownership, exact destructive + targeting and rollback. Findings return to the owning implementation task. +- The user resumed T05 after implementation fixes. Its automated and disposable + live-interface gates passed; the evidence records the final runtime guard + behavior and cleanup. + +## Acceptance criteria + +- [x] All four tools are discoverable and forward to the selected browser tab. +- [x] UI and MCP create equivalent stereotype/dataset project resources from + equivalent semantic requests. +- [x] UI can delete project stereotypes with confirmation; UI and MCP dataset + deletion share the same coordinator operation. +- [x] Core/in-use/dependency-required stereotype deletion is rejected without + mutation; valid deletions remove exact project resources and live entries. +- [x] Failures preserve graph, manifest, active scope and unrelated files. +- [x] No MCP-side catalog, generator or graph state is introduced. +- [x] T05 was resumed and completed with passing evidence. + +## Final verification + +T05 ran these gates on 2026-09-14: + +```bash +pnpm --dir front-end check +pnpm --dir front-end test +pnpm --dir front-end guard:package-only +pnpm --dir mcp-server test +git diff --check +``` + +It must also exercise create/delete for both resource types through the visible +UI and public MCP interface on a disposable project, compare disk/manifest/live +catalog state, reopen the project, and cover cancellation and rollback failure. + +Results: frontend check passed with 0 errors and 35 warnings; frontend tests +passed (302); package-only guard passed; MCP tests/build passed (74); and +`git diff --check` passed. The live acceptance cases passed on a disposable +copy of the existing VAE project. Full details are in the T05 evidence. + +## Knowledge and archive impact + +The UML parity and browser-MCP coverage documents were updated with the +implementation. The related dependency-guard issue was reproduced, fixed and +verified through live MCP. T05 passed and this initiative is complete. diff --git a/docs/plans/active/mcp-project-authoring-parity/tasks/T01-contract-and-kb.md b/docs/plans/active/mcp-project-authoring-parity/tasks/T01-contract-and-kb.md new file mode 100644 index 00000000..686771d2 --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/tasks/T01-contract-and-kb.md @@ -0,0 +1,25 @@ +--- +id: T01 +kind: task +status: done +plan: ../plan.md +role: architecture +depends_on: [] +parallel_with: [] +write_scope: + - docs/knowledge/uml/mcp-use-case-parity.md + - docs/plans/active/mcp-project-authoring-parity/ +--- + +# Fix the four project-authoring contracts + +## Objective + +Record the accepted UI/MCP parity, ownership and deletion-safety rules needed +for independent frontend and MCP implementation. + +## Acceptance criteria + +- [x] Four use cases and exact identities are explicit. +- [x] Shared browser ownership and JSON-only binary adaptation are explicit. +- [x] Destructive non-cascading and rollback rules are explicit. diff --git a/docs/plans/active/mcp-project-authoring-parity/tasks/T02-frontend-shared-authoring.md b/docs/plans/active/mcp-project-authoring-parity/tasks/T02-frontend-shared-authoring.md new file mode 100644 index 00000000..523101c5 --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/tasks/T02-frontend-shared-authoring.md @@ -0,0 +1,78 @@ +--- +id: T02 +kind: task +status: done +plan: ../plan.md +role: frontend +depends_on: [T01] +parallel_with: [T03] +write_scope: + - front-end/ +--- + +# Implement shared frontend authoring operations + +## Objective + +Make UI and browser RPC share create/delete operations for project stereotypes +and datasets, including a new confirmed stereotype-delete UI. + +## Context required + +Read the plan, UML parity decision, project-workspace stereotype decision, +project-owned dataset decision and browser-MCP architecture. Inspect the two +authoring coordinators, `FlowCanvas.svelte`, package manager/forms, +`BrowserRPCHandler`, project path adapter and focused tests. + +## Invariants + +- Browser project/DiagramCore owns live state; no second catalog or graph. +- Creation uses the existing request validators/generators and ordered writer. +- Stereotype deletion targets exact project identity and rejects core, in-use + and dependency-required packages without mutation or cascade. +- Deletion updates disk, model manifest and live scope transactionally. +- Dataset create/delete continues to synchronize training and type catalogs. +- RPC data files decode from strict base64 before domain validation. + +## Allowed files + +Any file under `front-end/`, limited to the narrow authoring, UI, RPC and test +seams needed for this objective. + +## Out of scope + +MCP server code, dataset update over MCP, rename/move, backend archive deletion, +or unrelated known UI bugs. + +## Work + +1. Add stereotype delete transaction and regression coverage. +2. Extract/bind one frontend authoring service used by UI callbacks and RPC. +3. Add the stereotype confirmation UI and keep core rows immutable. +4. Add four browser RPC cases with exact result/error behavior. +5. Add focused frontend tests; T05 executes the planned gates. + +## Acceptance criteria + +- [x] Four RPC calls and UI calls reach the same coordinators. +- [x] Equivalent create requests produce identical domain resources. +- [x] Safe stereotype delete and existing dataset delete update live state. +- [x] Failure/cancellation has no partial visible or persistent success. +- [x] No changes outside `front-end/`. + +## Validation + +Executed during T05: + +```bash +pnpm --dir front-end exec vitest run src/__tests__/projectStereotypeCreation.test.ts src/__tests__/projectDatasetAuthoring.test.ts src/__tests__/BrowserRPCHandler.test.ts +pnpm --dir front-end check +``` + +The focused authoring tests passed (10/10); the full frontend suite passed +(302/302) and `svelte-check` reported 0 errors. + +## Required handoff + +Handoff completed; T04 reviewed the integrated boundary and T05 passed final +automated and live-interface QA. diff --git a/docs/plans/active/mcp-project-authoring-parity/tasks/T03-mcp-authoring-tools.md b/docs/plans/active/mcp-project-authoring-parity/tasks/T03-mcp-authoring-tools.md new file mode 100644 index 00000000..986bc8bb --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/tasks/T03-mcp-authoring-tools.md @@ -0,0 +1,71 @@ +--- +id: T03 +kind: task +status: done +plan: ../plan.md +role: integration +depends_on: [T01] +parallel_with: [T02] +write_scope: + - mcp-server/ +--- + +# Expose project authoring through MCP + +## Objective + +Register four accurately typed MCP tools that validate JSON transport and proxy +the accepted requests to the selected browser tab. + +## Context required + +Read the plan and browser-MCP architecture. Inspect tool discovery/dispatch, +existing project and graph tool patterns, browser client, and MCP tests. + +## Invariants + +- Tools are thin adapters and keep no catalog, generator or project graph. +- Schemas expose every semantic UI request field with correct JSON types. +- Dataset data files use strict `{path, dataBase64}` JSON transport. +- Delete uses exact `{id, version, path}`; browser owns eligibility and domain + validation. + +## Allowed files + +Any file under `mcp-server/`, limited to tool registration/schema and tests. + +## Out of scope + +Frontend code, direct project-file authoring, backend calls, dataset update, +rename/move or compatibility-tool removal. + +## Work + +1. Add `create_stereotype`, `delete_stereotype`, `create_dataset`, and + `delete_dataset` tool schemas/handlers. +2. Reuse tool discovery and selected-tab BrowserRPCClient forwarding. +3. Add schema and proxy regression tests, including malformed base64/identity. +4. Defer test execution to T05. + +## Acceptance criteria + +- [x] Four tools appear through normal discovery. +- [x] Valid payloads are forwarded unchanged except documented JSON transport. +- [x] Invalid JSON shapes fail before browser mutation. +- [x] Browser/domain failures remain visible. +- [x] No changes outside `mcp-server/`. + +## Validation + +Executed during T05: + +```bash +pnpm --dir mcp-server test +``` + +The TypeScript build succeeded and all 74 MCP tests passed. + +## Required handoff + +Handoff completed; T04 reviewed the cross-boundary contract and T05 passed final +automated and live-interface QA. diff --git a/docs/plans/active/mcp-project-authoring-parity/tasks/T04-integration-review.md b/docs/plans/active/mcp-project-authoring-parity/tasks/T04-integration-review.md new file mode 100644 index 00000000..c1ebdf3e --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/tasks/T04-integration-review.md @@ -0,0 +1,28 @@ +--- +id: T04 +kind: task +status: done +plan: ../plan.md +role: review +depends_on: [T02, T03] +parallel_with: [] +write_scope: [] +--- + +# Review the integrated authoring boundary + +## Objective + +Read the combined diff and identify contract mismatches, ownership violations, +unsafe deletion or missing regression coverage before QA. + +## Acceptance criteria + +- [x] Tool schemas and browser RPC payloads agree field-for-field. +- [x] UI and RPC share domain operations. +- [x] Destructive paths are exact, non-cascading and rollback-safe. +- [x] No tests or live workflows are executed. + +## Validation + +Read-only diff inspection only. Return findings to T02 or T03 owners. diff --git a/docs/plans/active/mcp-project-authoring-parity/tasks/T05-final-qa.md b/docs/plans/active/mcp-project-authoring-parity/tasks/T05-final-qa.md new file mode 100644 index 00000000..0542dc4d --- /dev/null +++ b/docs/plans/active/mcp-project-authoring-parity/tasks/T05-final-qa.md @@ -0,0 +1,46 @@ +--- +id: T05 +kind: task +status: done +plan: ../plan.md +role: integration +depends_on: [T04] +parallel_with: [] +write_scope: + - docs/plans/active/mcp-project-authoring-parity/evidence/ +--- + +# Run final automated and real-interface QA + +## Objective + +Prove the four use cases through automated gates and a disposable live project, +then update current KB evidence/status without touching user projects. + +## Stop condition + +The user explicitly resumed QA. Final automated and live-interface QA passed; +see `../evidence/T05-final-qa.md`. + +## Work + +1. Load the repository `verify-task` and `nnmodelling-mcp` skills. +2. Run the plan's automated gates. +3. On a disposable project, create/delete each resource through UI and MCP; + compare manifest, exact directories, live catalogs and reopened state. +4. Exercise cancellation, core/in-use/dependency rejection and injected + persistence failure/rollback without deleting backend archives or jobs. +5. Record current evidence and update stale KB statements only after proof. + +## Acceptance criteria + +- [x] All automated gates pass with current results. +- [x] UI/MCP/disk parity is demonstrated for all four use cases. +- [x] Reopen and failure-path evidence proves transactionality. + +## Validation + +The full frontend suite passed (302 tests), the MCP suite passed (74 tests), +the package-only guard passed, and `svelte-check` reported 0 errors. Disposable +live QA covered both authoring channels, guarded and valid deletions, +cancellation, reopen and injected rollback failure. See the linked evidence. diff --git a/front-end/scripts/guard-package-only.mjs b/front-end/scripts/guard-package-only.mjs index 61d6b85a..dcf8646a 100644 --- a/front-end/scripts/guard-package-only.mjs +++ b/front-end/scripts/guard-package-only.mjs @@ -44,7 +44,7 @@ for (const directory of [join(repositoryRoot, "examples/diagrams")]) { if (!Array.isArray(document.nodes)) continue for (const node of document.nodes) { const identity = node?.data?.package - if (typeof identity?.id !== "string" || typeof identity?.version !== "string" || typeof identity?.name !== "string") { + if (typeof identity?.id !== "string" || typeof identity?.version !== "string") { failures.push(`${path} node ${String(node?.id)} lacks exact data.package identity`) } if (wrapped(node?.data?.params)) failures.push(`${path} node ${String(node?.id)} contains wrapped parameter values`) diff --git a/front-end/src/Diagram.svelte.ts b/front-end/src/Diagram.svelte.ts index 9406a272..7e6c4bc8 100644 --- a/front-end/src/Diagram.svelte.ts +++ b/front-end/src/Diagram.svelte.ts @@ -21,7 +21,7 @@ import type { LayoutDirection } from "./layout/autoLayout"; import type { DatasetInferenceContext, GraphInferenceResult } from "./type-system/graph/types"; import { EditorTypeSystemRuntime } from "./type-system/editor-runtime"; import type { ModelBundleResources, PackageCatalogMetadata, PreparedModelScope } from "./type-system/editor-runtime"; -import type { PackageExportInfo } from "./type-system/packages/types"; +import type { PackageExportInfo, PackageKey } from "./type-system/packages/types"; import type { PackageIdentity } from "./core/types"; import type { DatasetDefinition } from "./project-workspace/dataset-contract"; import type { DiagramCoreSnapshot } from "./core/types"; @@ -46,6 +46,7 @@ export class Diagram extends DiagramCore { public packageRuntimeDiagnostics: PackageRuntimeDiagnostic[] = $state.raw([]); /** Current dataset instance used to resolve top-level Input nodes. */ public datasetInferenceContext: DatasetInferenceContext | null = $state.raw(null); + private projectScopeTransition = false; private packageTypeRuntime: EditorTypeSystemRuntime | null = null; private readonly packageRuntimeReadyPromise: Promise; private readonly diagnosticCollection = new PackageRuntimeDiagnosticCollection(); @@ -135,6 +136,21 @@ export class Diagram extends DiagramCore { this.refreshTypes() } + /** Add only packages from the visible, committed scope. */ + public override addPackageNode( + identity: PackageIdentity, + kind: Parameters[1], + x: number, + y: number, + config?: Parameters[4], + ): Node { + const key: PackageKey = `${identity.id}@${identity.version}`; + if (this.projectScopeTransition || !this.packageCatalog.some((metadata) => metadata.key === key)) { + throw new Error(`package '${key}' is unavailable in the active project scope`); + } + return super.addPackageNode(identity, kind, x, y, config); + } + /** Presentation docking is intentionally limited to ordinary layer nodes. */ public isLayerNode(node: Node): boolean { const identity = node.data?.package as { id?: unknown; version?: unknown } | undefined; @@ -259,33 +275,83 @@ export class Diagram extends DiagramCore { } /** Commit one already-prepared scope through DiagramCore and refresh UI state. */ - public async commitPreparedProjectScope(prepared: { readonly snapshot: DiagramCoreSnapshot; readonly scope: PreparedModelScope }): Promise { - await this.packageRuntimeReadyPromise; - if (!this.packageTypeRuntime) throw new Error("package type-system is unavailable"); - this.commitProject(prepared.snapshot); - await this.packageTypeRuntime.commitModelScope(prepared.scope); - this.diagnosticCollection.clear(); - this.syncPackageCatalog(); - this.syncRuntimeDiagnostics(); - this.refreshTypes(); + public async commitPreparedProjectScope( + prepared: { readonly snapshot: DiagramCoreSnapshot; readonly scope: PreparedModelScope }, + options: { readonly preserveLiveGraph?: boolean } = {}, + ): Promise { + let runtime = this.packageTypeRuntime; + if (!runtime) { + await this.packageRuntimeReadyPromise; + runtime = this.packageTypeRuntime; + } + if (!runtime) throw new Error("package type-system is unavailable"); + + // Authoring prepares package resources asynchronously. Capture the graph + // at the synchronous commit boundary so edits made during staging are not + // replaced by the older graph included in the prepared model snapshot. + const snapshot = options.preserveLiveGraph + ? { ...this.getSnapshot(), manifest: prepared.snapshot.manifest } + : prepared.snapshot; + if (options.preserveLiveGraph) { + for (const node of snapshot.nodes) { + const identity = node.data?.package as { readonly id?: unknown; readonly version?: unknown } | undefined; + if (typeof identity?.id !== "string" || typeof identity.version !== "string") continue; + const key: PackageKey = `${identity.id}@${identity.version}`; + if (!prepared.scope.catalog.getExact(key) || prepared.scope.coordinator.status(key)?.state !== "active") { + throw new Error(`package '${key}' is unavailable in the prepared model scope`); + } + } + } + await this.commitProjectScopeSnapshot(snapshot, prepared.scope, runtime, { retainBarrierOnFailure: true }); } /** Restore a previously committed project after a failed authoring commit. */ public async restoreProjectScope(modelJson: string, modelBundle: ModelBundleResources): Promise { const prepared = await this.prepareProjectScope(modelJson, modelBundle); - await this.commitPreparedProjectScope(prepared); + await this.commitPreparedProjectScope(prepared, { preserveLiveGraph: true }); } private syncPackageCatalog(): void { + if (this.projectScopeTransition) return; if (this.packageTypeRuntime) this.packageCatalog = this.packageTypeRuntime.availablePackages(); } + /** Swap graph and runtime behind one package-addition barrier. */ + private async commitProjectScopeSnapshot( + snapshot: DiagramCoreSnapshot, + scope: PreparedModelScope, + runtime: EditorTypeSystemRuntime, + options: { readonly retainBarrierOnFailure?: boolean } = {}, + ): Promise { + this.projectScopeTransition = true; + this.packageCatalog = []; + try { + this.commitProject(snapshot); + await runtime.commitModelScope(scope); + } catch (cause) { + // Authoring callers keep additions disabled for their coordinated rollback. + // A plain model import has no rollback owner, so republish the runtime's + // current catalog if its scope swap cannot finish cleanly. + if (!options.retainBarrierOnFailure) { + this.projectScopeTransition = false; + this.syncPackageCatalog(); + } + throw cause; + } + this.projectScopeTransition = false; + this.diagnosticCollection.clear(); + this.syncPackageCatalog(); + this.syncRuntimeDiagnostics(); + this.refreshTypes(); + } + /** Reconcile exact package references before the single graph commit. */ public async importProjectJson(jsonString: string, modelBundle?: ModelBundleResources): Promise { const parsed = this.parseProjectJson(jsonString); if (!parsed) return false; await this.packageRuntimeReadyPromise; - if (this.packageTypeRuntime) { + const runtime = this.packageTypeRuntime; + if (runtime) { let prepared; try { const graphIdentities = parsed.nodes.flatMap((node) => { @@ -294,7 +360,7 @@ export class Diagram extends DiagramCore { ? [{ id: identity.id, version: identity.version, ...(typeof identity.name === "string" ? { name: identity.name } : {}) }] : []; }); - prepared = await this.packageTypeRuntime.prepareModelScope(parsed.manifest, modelBundle, graphIdentities); + prepared = await runtime.prepareModelScope(parsed.manifest, modelBundle, graphIdentities); } catch (error) { this.diagnosticCollection.record({ occurrenceId: `runtime:model-switch:${parsed.manifest.id}@${parsed.manifest.version}`, @@ -304,14 +370,9 @@ export class Diagram extends DiagramCore { this.publishDiagnostics(); return false; } - // DiagramCore remains the graph authority: prepare all package runtime - // resources first, then commit the parsed graph and finally swap scopes. - this.commitProject(parsed); - await this.packageTypeRuntime.commitModelScope(prepared); - this.diagnosticCollection.clear(); - this.syncPackageCatalog(); - this.syncRuntimeDiagnostics(); - this.refreshTypes(); + // DiagramCore remains the graph authority; imports share the same + // package-addition barrier as transactional authoring scope swaps. + await this.commitProjectScopeSnapshot(parsed, prepared, runtime); return true; } this.commitProject(parsed); diff --git a/front-end/src/FlowCanvas.svelte b/front-end/src/FlowCanvas.svelte index 5bab3565..e6cfd43b 100644 --- a/front-end/src/FlowCanvas.svelte +++ b/front-end/src/FlowCanvas.svelte @@ -57,9 +57,11 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. // 1. Importiamo la classe Diagram import { Diagram, DIAGRAM_CONTEXT_KEY } from "./Diagram.svelte"; import { setContext, tick } from "svelte"; + import type { ModelPackageReference } from "./core/types"; import type { ProjectSaveStatus, ProjectWorkspaceSession } from "./project-workspace"; import { ProjectStereotypeAuthoringCoordinator } from "./project-workspace"; import { ProjectDatasetAuthoringCoordinator, type DatasetAuthoringRequest, type GeneratedDatasetResources } from "./project-workspace/dataset-authoring"; + import { ProjectAuthoringService } from "./project-workspace/authoring-service"; import type { DatasetParameterValue, DatasetReference, ModelDatasetReference } from "./project-workspace/dataset-contract"; import type { StereotypeAuthoringRequest } from "./stereotype-authoring"; import type { DatasetInfo } from "./training/api"; @@ -169,7 +171,11 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. } function authorStereotype(request: StereotypeAuthoringRequest): Promise { - return stereotypeAuthoring.author(request).then(() => undefined); + return authoringService.createStereotype(request).then(() => undefined); + } + + function deleteStereotype(target: ModelPackageReference): Promise { + return authoringService.deleteStereotype(target).then(() => undefined); } function datasetReference(modelDataset: ModelDatasetReference): DatasetReference { @@ -198,17 +204,14 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. } async function authorDataset(request: DatasetAuthoringRequest): Promise { - const { generated } = await datasetAuthoring.author(request); - installProjectDataset(generated); + await authoringService.createDataset(request); } async function updateDataset(target: ModelDatasetReference, request: DatasetAuthoringRequest): Promise { - const { generated } = await datasetAuthoring.update(target, request); - installProjectDataset(generated); + await authoringService.updateDataset(target, request); } - async function deleteDataset(target: ModelDatasetReference): Promise { - await datasetAuthoring.delete(target); + function removeProjectDataset(target: ModelDatasetReference): void { const reference = datasetReference(target); projectDatasetInfos = projectDatasetInfos.filter((dataset) => dataset.reference.ref !== reference.ref); const nextResources = new Map(projectDatasetResources); @@ -218,6 +221,15 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. diagram.setDatasetCatalog(projectDatasetInfos.map((dataset) => dataset.definition)); } + const authoringService = new ProjectAuthoringService(stereotypeAuthoring, datasetAuthoring, { + installDataset: installProjectDataset, + removeDataset: removeProjectDataset, + }); + + function deleteDataset(target: ModelDatasetReference): Promise { + return authoringService.deleteDataset(target).then(() => undefined); + } + // Stage package-aware import before exposing Svelte Flow. New projects carry // an empty graph, so retain Diagram's normal bootstrap Input and save that // accepted initial graph through the same writer. @@ -320,10 +332,14 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. let syncClient: BrowserRPCHandler; $effect(() => { - syncClient = rpcHandler ?? new BrowserRPCHandler(diagram, undefined, { fitView, setCenter }, trainingController); + syncClient = rpcHandler ?? new BrowserRPCHandler(diagram, undefined, { fitView, setCenter }, trainingController, undefined, authoringService); if (rpcHandler) { syncClient.bindDiagram(diagram); - return () => syncClient.bindDiagram(undefined); + syncClient.bindAuthoringService(authoringService); + return () => { + syncClient.bindDiagram(undefined); + syncClient.bindAuthoringService(undefined); + }; } syncClient.connect(); return () => syncClient.disconnect(); @@ -787,7 +803,9 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. > = [] @@ -115,3 +116,103 @@ describe("BrowserRPCHandler training download", () => { expect(sent[0]?.result).toEqual({ status: "ok" }) }) }) + +describe("BrowserRPCHandler project authoring", () => { + test("routes all four top-level requests to the shared project operations", async () => { + const stereotype = { id: "model.custom", version: "1.0.0", path: "packages/custom" } + const dataset = { id: "demo.tokens", version: "1.0.0", path: "datasets/tokens" } + const authoring: ProjectAuthoringOperations = { + createStereotype: vi.fn().mockResolvedValue(stereotype), + deleteStereotype: vi.fn().mockResolvedValue(stereotype), + createDataset: vi.fn().mockResolvedValue(dataset), + deleteDataset: vi.fn().mockResolvedValue(dataset), + } + const diagram = { nodes: [], edges: [], packageCatalog: [] } as any + const sent: Array> = [] + const handler: any = new BrowserRPCHandler(diagram, "ws://test", undefined, undefined, undefined, authoring) + handler.ws = { readyState: 1, send(payload: string) { sent.push(JSON.parse(payload)) } } + const stereotypeRequest = { + id: "model.custom", + version: "1.0.0", + directory: "packages/custom", + name: "Custom", + kind: "layer", + view: { color: "#123456", width: 120, height: 80 }, + dependencies: { "core.relu": "^0.1.0" }, + parameters: [], + } + const datasetRequest = { + id: "demo.tokens", + version: "1.0.0", + directory: "datasets/tokens", + name: "Tokens", + parameters: [], + inputs: [{ name: "tokens", shape: ["B", "T"], dtype: "int64" }], + targets: [{ name: "next_tokens", shape: ["B", "T"], dtype: "int64" }], + classes: { count: 2, names: ["no", "yes"] }, + dataFiles: [{ path: "train.pt", dataBase64: "AQID" }], + } + const calls = [ + { id: "create-stereotype", method: "create_stereotype", params: stereotypeRequest }, + { id: "delete-stereotype", method: "delete_stereotype", params: stereotype }, + { id: "create-dataset", method: "create_dataset", params: datasetRequest }, + { id: "delete-dataset", method: "delete_dataset", params: dataset }, + ] + for (const call of calls) handler.handleMessage({ data: JSON.stringify(call) }) + await new Promise((resolve) => setTimeout(resolve, 0)) + + expect(authoring.createStereotype).toHaveBeenCalledWith(stereotypeRequest) + expect(authoring.deleteStereotype).toHaveBeenCalledWith(stereotype) + expect(authoring.createDataset).toHaveBeenCalledWith({ + ...datasetRequest, + dataFiles: [{ path: "train.pt", bytes: new Uint8Array([1, 2, 3]) }], + }) + expect(authoring.deleteDataset).toHaveBeenCalledWith(dataset) + expect(sent.map((response) => response.result)).toEqual([stereotype, stereotype, dataset, dataset]) + }) + + test("rejects non-canonical dataset base64 before the shared coordinator runs", async () => { + const createDataset = vi.fn() + const authoring = { + createStereotype: vi.fn(), + deleteStereotype: vi.fn(), + createDataset, + deleteDataset: vi.fn(), + } as unknown as ProjectAuthoringOperations + const sent: Array> = [] + const handler: any = new BrowserRPCHandler({} as any, "ws://test", undefined, undefined, undefined, authoring) + handler.ws = { readyState: 1, send(payload: string) { sent.push(JSON.parse(payload)) } } + + handler.handleMessage({ data: JSON.stringify({ + id: "bad-dataset", + method: "create_dataset", + params: { id: "demo.tokens", dataFiles: [{ path: "train.pt", dataBase64: "AB==" }] }, + }) }) + await new Promise((resolve) => setTimeout(resolve, 0)) + + expect(createDataset).not.toHaveBeenCalled() + expect(sent[0]?.error).toMatchObject({ message: expect.stringMatching(/canonical base64/) }) + }) + + test("returns coordinator failures without reporting a successful delete", async () => { + const authoring: ProjectAuthoringOperations = { + createStereotype: vi.fn(), + deleteStereotype: vi.fn().mockRejectedValue(new Error("stereotype is required by another package")), + createDataset: vi.fn(), + deleteDataset: vi.fn(), + } + const sent: Array> = [] + const handler: any = new BrowserRPCHandler({} as any, "ws://test", undefined, undefined, undefined, authoring) + handler.ws = { readyState: 1, send(payload: string) { sent.push(JSON.parse(payload)) } } + + handler.handleMessage({ data: JSON.stringify({ + id: "blocked-delete", + method: "delete_stereotype", + params: { id: "model.custom", version: "1.0.0", path: "packages/custom" }, + }) }) + await new Promise((resolve) => setTimeout(resolve, 0)) + + expect(sent[0]?.result).toBeUndefined() + expect(sent[0]?.error).toEqual({ message: "stereotype is required by another package" }) + }) +}) diff --git a/front-end/src/__tests__/diagramProjectScopeTransition.test.ts b/front-end/src/__tests__/diagramProjectScopeTransition.test.ts new file mode 100644 index 00000000..095c57de --- /dev/null +++ b/front-end/src/__tests__/diagramProjectScopeTransition.test.ts @@ -0,0 +1,96 @@ +import { afterAll, afterEach, describe, expect, test } from "vitest" + +import { Diagram } from "../Diagram.svelte" +import type { EditorTypeSystemRuntime } from "../type-system/editor-runtime" +import { stubWindow, unstubWindow } from "./helpers" + +stubWindow() + +const packageReference = { id: "model.transition-probe", version: "1.0.0", path: "packages/transition-probe" } +const oldManifest = { + schemaVersion: 1 as const, + id: "model.old", + version: "1.0.0", + name: "Old model", + customPackages: [packageReference], +} +const oldModel = JSON.stringify({ manifest: oldManifest, nodes: [], edges: [] }) +const newModel = JSON.stringify({ + manifest: { schemaVersion: 1, id: "model.new", version: "1.0.0", name: "New model", customPackages: [] }, + nodes: [], + edges: [], +}) +const oldResources = { + "packages/transition-probe/manifest.json": JSON.stringify({ + schemaVersion: 1, + id: packageReference.id, + version: packageReference.version, + dependencies: {}, + entrypoints: { + definition: "stereotype.json", + inference: { language: "lua", file: "inference.lua" }, + }, + }), + "packages/transition-probe/stereotype.json": JSON.stringify({ + name: "Transition probe", + kind: "layer", + view: { color: "#123456", width: 100, height: 60 }, + parameters: {}, + }), + "packages/transition-probe/inference.lua": "return function(context) return { status = 'success', output = context.inputs[1] } end", +} + +const diagrams: Diagram[] = [] + +afterEach(async () => { + for (const diagram of diagrams.splice(0)) { + await (diagram as unknown as { packageTypeRuntime: EditorTypeSystemRuntime }).packageTypeRuntime.dispose() + } +}) +afterAll(() => unstubWindow()) + +describe("Diagram project scope transition", () => { + test("blocks old-scope package additions while an import swaps the runtime", async () => { + const diagram = new Diagram() + diagrams.push(diagram) + await diagram.waitForPackageRuntime() + await expect(diagram.importProjectJson(oldModel, oldResources)).resolves.toBe(true) + expect(diagram.packageCatalog.some(({ id, version }) => id === packageReference.id && version === packageReference.version)).toBe(true) + + const runtime = (diagram as unknown as { packageTypeRuntime: EditorTypeSystemRuntime }).packageTypeRuntime + const mutableRuntime = runtime as EditorTypeSystemRuntime & { commitModelScope: typeof runtime.commitModelScope } + const originalCommit = runtime.commitModelScope.bind(runtime) + let enteredCommit!: () => void + let releaseCommit!: () => void + const commitEntered = new Promise((resolve) => { enteredCommit = resolve }) + const holdCommit = new Promise((resolve) => { releaseCommit = resolve }) + mutableRuntime.commitModelScope = async (scope) => { + enteredCommit() + await holdCommit + return originalCommit(scope) + } + + const importing = diagram.importProjectJson(newModel) + try { + await commitEntered + expect(diagram.packageCatalog).toEqual([]) + expect(() => diagram.addPackageNode( + { id: packageReference.id, version: packageReference.version, name: "Transition probe" }, + "layer", + 30, + 30, + )).toThrow(/unavailable in the active project scope/) + releaseCommit() + await expect(importing).resolves.toBe(true) + expect(diagram.packageCatalog.some(({ id }) => id === packageReference.id)).toBe(false) + expect(diagram.nodes.some((node) => ( + node.data?.package && + (node.data.package as { id?: string; version?: string }).id === packageReference.id + ))).toBe(false) + } finally { + releaseCommit() + mutableRuntime.commitModelScope = originalCommit + await importing.catch(() => undefined) + } + }) +}) diff --git a/front-end/src/__tests__/packageManager.test.ts b/front-end/src/__tests__/packageManager.test.ts index 3138a412..c8604ff5 100644 --- a/front-end/src/__tests__/packageManager.test.ts +++ b/front-end/src/__tests__/packageManager.test.ts @@ -1,5 +1,5 @@ import { describe, expect, test } from "vitest" -import PackageManager from "../components/PackageManager.svelte" +import PackageManager, { modelPackageDeleteTarget } from "../components/PackageManager.svelte" import type { PackageManagerPackage } from "../components/PackageManager.svelte" const definition = (name: string) => ({ name, kind: "layer" as const, view: { color: "#123456", width: 100, height: 80 }, parameters: {} }) @@ -19,4 +19,11 @@ describe("Stereotype manager", () => { expect(packages.filter((item) => item.source === "model").map((item) => item.definition.name)).toEqual(["Project layer"]) expect(packages.some((item) => item.source === "external")).toBe(true) }) + + test("only resolves exact active-project identities for confirmed deletion", () => { + const modelPackages = [{ id: "model.layer", version: "1.0.0", path: "packages/layer" }] + expect(modelPackageDeleteTarget({ key: "core.relu@1.0.0", source: "bundled" }, modelPackages)).toBeUndefined() + expect(modelPackageDeleteTarget({ key: "model.layer@1.0.0", source: "model" }, modelPackages)).toEqual(modelPackages[0]) + expect(modelPackageDeleteTarget({ key: "model.layer@2.0.0", source: "model" }, modelPackages)).toBeUndefined() + }) }) diff --git a/front-end/src/__tests__/projectDatasetAuthoring.test.ts b/front-end/src/__tests__/projectDatasetAuthoring.test.ts index 69ba65e6..3473ccf6 100644 --- a/front-end/src/__tests__/projectDatasetAuthoring.test.ts +++ b/front-end/src/__tests__/projectDatasetAuthoring.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, test } from "vitest" +import { describe, expect, test, vi } from "vitest" import { createProjectWorkspace, openProjectWorkspace, @@ -12,8 +12,10 @@ import { ProjectDatasetAuthoringCoordinator, generateDatasetResources, readDatasetDataFile, + type GeneratedDatasetResources, } from "../project-workspace/dataset-authoring" -import type { ModelManifestV2 } from "../project-workspace/dataset-contract" +import { ProjectAuthoringService } from "../project-workspace/authoring-service" +import type { ModelDatasetReference, ModelManifestV2 } from "../project-workspace/dataset-contract" class MemoryFile implements ProjectFile { constructor(public value: string | Uint8Array) {} @@ -280,6 +282,94 @@ describe("project dataset authoring", () => { expect(restored.nodes).toEqual([{ id: "latest", position: { x: 350, y: 20 } }]) expect(restored.manifest.customDatasets).toEqual([]) }) + + test("shared project authoring returns exact identities and synchronizes dataset catalogs", async () => { + const parent = new MemoryDirectory() + const session = await createProjectWorkspace(parent, "demo", MODEL) + const stereotypeIdentity = { id: "model.custom", version: "1.0.0", path: "packages/custom" } + const stereotypes = { + author: vi.fn().mockResolvedValue({ generated: { modelPackage: stereotypeIdentity }, modelJson: MODEL } as never), + delete: vi.fn().mockResolvedValue(stereotypeIdentity), + } + const installed: GeneratedDatasetResources[] = [] + const removed: ModelDatasetReference[] = [] + const service = new ProjectAuthoringService( + stereotypes, + new ProjectDatasetAuthoringCoordinator(session), + { installDataset: (generated) => installed.push(generated), removeDataset: (target) => removed.push(target) }, + ) + + await expect(service.createStereotype({ + id: "model.custom", + version: "1.0.0", + directory: "packages/custom", + name: "Custom", + kind: "layer", + view: { color: "#123456", width: 100, height: 80 }, + parameters: [], + })).resolves.toEqual(stereotypeIdentity) + await expect(service.deleteStereotype(stereotypeIdentity)).resolves.toEqual(stereotypeIdentity) + + const createdDataset = await service.createDataset(REQUEST) + expect(createdDataset).toEqual({ id: "demo.tokens", version: "1.0.0", path: "datasets/tokens" }) + expect(installed).toHaveLength(1) + expect(installed[0]?.modelDataset).toEqual(createdDataset) + await expect(service.deleteDataset(createdDataset)).resolves.toEqual(createdDataset) + expect(removed).toEqual([createdDataset]) + expect(new ProjectDatasetAuthoringCoordinator(session).listProjectDatasets()).toEqual([]) + }) + + test("serializes stereotype and dataset mutations through the shared service", async () => { + const stereotypeIdentity = { id: "model.custom", version: "1.0.0", path: "packages/custom" } + let releaseStereotype!: () => void + const stereotypeBlocked = new Promise((resolve) => { releaseStereotype = resolve }) + const order: string[] = [] + const stereotypes = { + author: vi.fn(async () => { + order.push("stereotype-start") + await stereotypeBlocked + order.push("stereotype-end") + return { generated: { modelPackage: stereotypeIdentity }, modelJson: MODEL } as never + }), + delete: vi.fn().mockResolvedValue(stereotypeIdentity), + } + const generated = generateDatasetResources(REQUEST) + const datasets = { + author: vi.fn(async () => { + order.push("dataset") + return { generated, modelJson: MODEL } + }), + update: vi.fn(), + delete: vi.fn(), + } + const service = new ProjectAuthoringService( + stereotypes, + datasets, + { installDataset: () => undefined, removeDataset: () => undefined }, + ) + + const stereotypeRequest = { + id: "model.custom", + version: "1.0.0", + directory: "packages/custom", + name: "Custom", + kind: "layer" as const, + view: { color: "#123456", width: 100, height: 80 }, + parameters: [], + } + const stereotypeOperation = service.createStereotype(stereotypeRequest) + const datasetOperation = service.createDataset(REQUEST) + await Promise.resolve() + expect(order).toEqual(["stereotype-start"]) + expect(datasets.author).not.toHaveBeenCalled() + + releaseStereotype() + await expect(Promise.all([stereotypeOperation, datasetOperation])).resolves.toEqual([ + stereotypeIdentity, + generated.modelDataset, + ]) + expect(order).toEqual(["stereotype-start", "stereotype-end", "dataset"]) + }) }) function datasetBytes(value: string | Uint8Array): Uint8Array { diff --git a/front-end/src/__tests__/projectStereotypeCreation.test.ts b/front-end/src/__tests__/projectStereotypeCreation.test.ts index cd860142..1ced8783 100644 --- a/front-end/src/__tests__/projectStereotypeCreation.test.ts +++ b/front-end/src/__tests__/projectStereotypeCreation.test.ts @@ -2,13 +2,17 @@ import { afterEach, describe, expect, test } from "vitest" import { ProjectStereotypeAuthoringCoordinator, createProjectWorkspace, + openProjectWorkspace, readProjectWorkspace, + writeProjectFiles, type ProjectDirectoryHandle, type ProjectFile, type ProjectFileHandle, type ProjectWritableFile, } from "../project-workspace" -import type { ModelManifest } from "../core/types" +import type { DiagramCoreSnapshot, ModelManifest } from "../core/types" +import { generateStereotypePackage } from "../stereotype-authoring" +import { resolveModelPackageRecords } from "../type-system/editor-runtime" class File implements ProjectFile { constructor(public value: string | Uint8Array) {} @@ -28,6 +32,7 @@ class Directory implements ProjectDirectoryHandle { readonly kind = "directory" as const readonly directories = new Map() readonly files = new Map() + removalFailure: Error | undefined constructor(readonly name = "root") {} async getDirectoryHandle(name: string, options?: { create?: boolean }): Promise { const current = this.directories.get(name) @@ -49,7 +54,10 @@ class Directory implements ProjectDirectoryHandle { for (const [name, value] of this.directories) yield [name, value] for (const [name, value] of this.files) yield [name, value] } - async removeEntry(name: string): Promise { this.directories.delete(name) } + async removeEntry(name: string): Promise { + if (this.removalFailure) throw this.removalFailure + this.directories.delete(name) + } } const manifest: ModelManifest = { schemaVersion: 1, id: "demo", version: "1.0.0", name: "Demo", customPackages: [] } @@ -103,24 +111,267 @@ describe("project stereotype authoring transaction", () => { expect(loaded.resources).not.toHaveProperty("packages/custom/manifest.json") expect(diagram.restores).toBe(1) }) + + test("preserves graph edits made while the created package scope is preparing", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + diagram.beforePrepare = async () => { + diagram.beforePrepare = undefined + await Promise.resolve() + diagram.addGraphNode("concurrent-create") + } + + await coordinator.author(request) + + const persisted = JSON.parse((await readProjectWorkspace(session.directory)).modelJson) + expect(persisted.nodes).toContainEqual(expect.objectContaining({ id: "concurrent-create" })) + expect(JSON.parse(diagram.exportToJson()).nodes).toContainEqual(expect.objectContaining({ id: "concurrent-create" })) + }) + + test("deletes one exact project stereotype and commits the reduced live scope", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + + await expect(coordinator.delete(generated.modelPackage)).resolves.toEqual(generated.modelPackage) + + const loaded = await readProjectWorkspace(session.directory) + expect(JSON.parse(loaded.modelJson).manifest.customPackages).toEqual([]) + expect(Object.keys(loaded.resources)).toEqual(["model.json"]) + expect(diagram.modelManifest.customPackages).toEqual([]) + expect(diagram.commits).toBe(2) + }) + + test("preserves graph edits made while the reduced package scope is preparing", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + diagram.beforePrepare = async () => { + diagram.beforePrepare = undefined + await Promise.resolve() + diagram.addGraphNode("concurrent-delete") + } + + await coordinator.delete(generated.modelPackage) + + const persisted = JSON.parse((await readProjectWorkspace(session.directory)).modelJson) + expect(persisted.nodes).toContainEqual(expect.objectContaining({ id: "concurrent-delete" })) + expect(JSON.parse(diagram.exportToJson()).nodes).toContainEqual(expect.objectContaining({ id: "concurrent-delete" })) + }) + + test("does not add a deleted package while the asynchronous scope swap is committing", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + let rejectedDuringSwap = false + diagram.beforeScopeSwap = async () => { + await Promise.resolve() + try { + diagram.addPackageNode(generated.modelPackage.id, generated.modelPackage.version) + } catch { + rejectedDuringSwap = true + } + } + + await coordinator.delete(generated.modelPackage) + + const persisted = JSON.parse((await readProjectWorkspace(session.directory)).modelJson) + expect(rejectedDuringSwap).toBe(true) + expect(persisted.manifest.customPackages).toEqual([]) + expect(persisted.nodes.some((node: { data?: { package?: { id?: string; version?: string } } }) => ( + node.data?.package?.id === generated.modelPackage.id && + node.data.package.version === generated.modelPackage.version + ))).toBe(false) + }) + + test("rejects core, graph-used, and dependency-required targets without mutation", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + const before = await readProjectWorkspace(session.directory) + + await expect(coordinator.delete({ id: "core.relu", version: "1.0.0", path: "packages/relu" })).rejects.toThrow(/not owned/) + await expect(coordinator.delete({ ...generated.modelPackage, path: "packages/other" })).rejects.toThrow(/not owned/) + diagram.addPackageNode(generated.modelPackage.id, generated.modelPackage.version) + await expect(coordinator.delete(generated.modelPackage)).rejects.toThrow(/used by the project graph/) + diagram.clearGraph() + diagram.exports.set("model.dependent@1.0.0", { + manifest: { schemaVersion: 1, id: "model.dependent", version: "1.0.0", dependencies: {}, entrypoints: { definition: "stereotype.json" } }, + definition: { name: "Dependent", kind: "layer", view: { color: "#000000", width: 1, height: 1 }, parameters: {} }, + resolvedDependencies: { "model.custom": "model.custom@1.0.0" }, + state: "failed", + }) + await expect(coordinator.delete(generated.modelPackage)).rejects.toThrow(/required by another/) + + expect(await readProjectWorkspace(session.directory)).toEqual(before) + expect(diagram.modelManifest.customPackages).toEqual([generated.modelPackage]) + }) + + test("rejects deleting a dependency from package records loaded by the model runtime", async () => { + parent = new Directory() + const target = generateStereotypePackage({ + ...request, + id: "qa.mcp-layer", + directory: "packages/qa.mcp-layer", + }) + const dependent = { + id: "qa.dependent", + version: "1.0.0", + path: "packages/qa.dependent", + } + const dependentManifest = { + schemaVersion: 1, + id: dependent.id, + version: dependent.version, + dependencies: { "qa.mcp-layer": "^1.0.0" }, + entrypoints: { definition: "stereotype.json" }, + } + const dependentDefinition = { + name: "Dependent", + kind: "layer", + view: { color: "#123456", width: 100, height: 60 }, + parameters: {}, + } + const projectManifest: ModelManifest = { + ...manifest, + customPackages: [target.modelPackage, dependent], + } + const projectJson = JSON.stringify({ manifest: projectManifest, nodes: [], edges: [] }) + const projectFiles = { + "model.json": projectJson, + ...Object.fromEntries(Object.entries(target.files).map(([path, value]) => [`${target.modelPackage.path}/${path}`, value])), + [`${dependent.path}/manifest.json`]: JSON.stringify(dependentManifest), + [`${dependent.path}/stereotype.json`]: JSON.stringify(dependentDefinition), + } + await writeProjectFiles(parent, projectFiles) + const session = await openProjectWorkspace(parent) + const runtimeRecords = await resolveModelPackageRecords(projectManifest, session.resources) + const diagram = new FakeDiagram(projectManifest, projectJson) + diagram.exports = new Map(runtimeRecords.map((record) => [record.key, { + manifest: record.manifest, + definition: record.definition, + resources: record.resources, + resolvedDependencies: record.resolvedDependencies, + }])) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + + await expect(coordinator.delete(target.modelPackage)).rejects.toThrow(/required by another project stereotype/) + + expect(runtimeRecords.find((record) => record.manifest.id === dependent.id)?.resolvedDependencies) + .toEqual({ "qa.mcp-layer": "qa.mcp-layer@1.0.0" }) + expect(await readProjectWorkspace(session.directory)).toEqual({ + modelJson: session.modelJson, + resources: session.resources, + }) + }) + + test("restores the exact package and manifest when deletion cannot finish", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + const packages = await session.directory.getDirectoryHandle("packages") as Directory + packages.removalFailure = new Error("directory is busy") + + await expect(coordinator.delete(generated.modelPackage)).rejects.toThrow(/directory is busy/) + + const restored = await readProjectWorkspace(session.directory) + expect(JSON.parse(restored.modelJson).manifest.customPackages).toEqual([generated.modelPackage]) + expect(restored.resources).toHaveProperty("packages/custom/stereotype.json") + expect(diagram.modelManifest.customPackages).toEqual([generated.modelPackage]) + }) + + test("restores package files, manifest, and active scope after commit failure", async () => { + parent = new Directory() + const session = await createProjectWorkspace(parent, "demo", modelJson) + const diagram = new FakeDiagram(manifest, modelJson) + const coordinator = new ProjectStereotypeAuthoringCoordinator(session, diagram) + const { generated } = await coordinator.author(request) + diagram.failCommit = true + + await expect(coordinator.delete(generated.modelPackage)).rejects.toThrow(/activation failed/) + + const restored = await readProjectWorkspace(session.directory) + expect(JSON.parse(restored.modelJson).manifest.customPackages).toEqual([generated.modelPackage]) + expect(restored.resources).toHaveProperty("packages/custom/stereotype.json") + expect(diagram.modelManifest.customPackages).toEqual([generated.modelPackage]) + expect(diagram.restores).toBe(1) + }) }) class FakeDiagram { commits = 0 restores = 0 + failCommit: boolean + exports = new Map() + beforePrepare: (() => Promise | void) | undefined + beforeScopeSwap: (() => Promise | void) | undefined + private scopeTransition = false + private visiblePackages = new Set() + private project: Record constructor( public modelManifest: ModelManifest, - private readonly json: string, - private readonly failCommit = false, - ) {} - exportToJson(): string { return this.json } + json: string, + failCommit = false, + ) { + this.project = JSON.parse(json) as Record + this.failCommit = failCommit + } + exportToJson(): string { return JSON.stringify({ ...this.project, manifest: this.modelManifest }) } + packageExports() { return this.exports } + addPackageNode(id: string, version: string): void { + const key = `${id}@${version}` + if (this.scopeTransition || !this.visiblePackages.has(key)) throw new Error(`package '${key}' is unavailable`) + this.project.nodes = [{ id: "node", data: { package: { id, version } } }] + } + addGraphNode(id: string): void { + const nodes = Array.isArray(this.project.nodes) ? this.project.nodes : [] + this.project.nodes = [...nodes, { id, position: { x: 350, y: 20 }, data: { concurrent: true } }] + } + clearGraph(): void { this.project.nodes = [] } async prepareProjectScope(modelJson: string, modelBundle: Record) { - return { snapshot: { manifest: JSON.parse(modelJson).manifest, nodes: [], edges: [], layoutDirection: "vertical" }, scope: { modelBundle } } as never + const project = JSON.parse(modelJson) as Record + const beforePrepare = this.beforePrepare + this.beforePrepare = undefined + await beforePrepare?.() + return { snapshot: { manifest: project.manifest, nodes: project.nodes ?? [], edges: project.edges ?? [], layoutDirection: "vertical" }, scope: { modelBundle } } as never } - async commitPreparedProjectScope(): Promise { + async commitPreparedProjectScope( + prepared: { readonly snapshot: DiagramCoreSnapshot }, + options: { readonly preserveLiveGraph?: boolean } = {}, + ): Promise { this.commits += 1 + const current = JSON.parse(this.exportToJson()) as DiagramCoreSnapshot + const snapshot = options.preserveLiveGraph + ? { ...prepared.snapshot, ...current, manifest: prepared.snapshot.manifest } + : prepared.snapshot + this.modelManifest = snapshot.manifest + this.project = { ...snapshot } + this.scopeTransition = true + this.visiblePackages.clear() + const beforeScopeSwap = this.beforeScopeSwap + this.beforeScopeSwap = undefined + await beforeScopeSwap?.() if (this.failCommit) throw new Error("activation failed") + this.visiblePackages = new Set(snapshot.manifest.customPackages.map((candidate) => `${candidate.id}@${candidate.version}`)) + this.scopeTransition = false + } + async restoreProjectScope(modelJson: string): Promise { + this.restores += 1 + this.project = JSON.parse(modelJson) as Record + this.modelManifest = this.project.manifest as ModelManifest + this.visiblePackages = new Set(this.modelManifest.customPackages.map((candidate) => `${candidate.id}@${candidate.version}`)) + this.scopeTransition = false } - async restoreProjectScope(): Promise { this.restores += 1 } } - diff --git a/front-end/src/components/PackageManager.svelte b/front-end/src/components/PackageManager.svelte index be1f1c7a..8ecec965 100644 --- a/front-end/src/components/PackageManager.svelte +++ b/front-end/src/components/PackageManager.svelte @@ -1,9 +1,23 @@ + +
@@ -47,14 +88,39 @@

{t("User packages")}

{#each project as packageInfo (packageInfo.key)} + {@const target = modelPackageDeleteTarget(packageInfo, modelPackages)}
{packageInfo.definition.name}{packageInfo.key} {t("Project")} + {#if target && onStereotypeDeleteRequest} + + {/if}
{/each}
{/if} + {#if pendingStereotypeDeletion} +
+

{t("Delete this project stereotype and its folder?")}

+ {pendingStereotypeDeletion.id}@{pendingStereotypeDeletion.version} · {pendingStereotypeDeletion.path} + {#if stereotypeDeletionError} + + {/if} +
+ + +
+
+ {/if} +

{t("Create new")}

diff --git a/front-end/src/i18n.ts b/front-end/src/i18n.ts index d7fee833..e1dd241e 100644 --- a/front-end/src/i18n.ts +++ b/front-end/src/i18n.ts @@ -185,6 +185,8 @@ const italianMessages: Record = { "Delete {name}, its project folder, and its active training entry?": "Eliminare {name}, la cartella del progetto e la relativa voce di training attiva?", "Deleting…": "Eliminazione…", "Delete dataset": "Elimina dataset", + "Delete this project stereotype and its folder?": "Eliminare questo stereotype del progetto e la relativa cartella?", + "Delete stereotype": "Elimina stereotype", "Dataset updated.": "Dataset aggiornato.", "Dataset created.": "Dataset creato.", "Identity and metadata": "Identità e metadati", diff --git a/front-end/src/project-workspace/authoring-service.ts b/front-end/src/project-workspace/authoring-service.ts new file mode 100644 index 00000000..28652b3c --- /dev/null +++ b/front-end/src/project-workspace/authoring-service.ts @@ -0,0 +1,80 @@ +import type { ModelPackageReference } from "../core/types" +import type { StereotypeAuthoringRequest } from "../stereotype-authoring" +import type { + DatasetAuthoringRequest, + GeneratedDatasetResources, + ProjectDatasetAuthoringCoordinator, +} from "./dataset-authoring" +import type { ModelDatasetReference } from "./dataset-contract" +import type { ProjectStereotypeAuthoringCoordinator } from "./authoring" + +/** The browser-owned operations shared by visible forms and browser RPC. */ +export interface ProjectAuthoringOperations { + createStereotype(request: StereotypeAuthoringRequest): Promise + deleteStereotype(target: ModelPackageReference): Promise + createDataset(request: DatasetAuthoringRequest): Promise + deleteDataset(target: ModelDatasetReference): Promise +} + +export type ProjectAuthoringServiceEffects = { + readonly installDataset: (generated: GeneratedDatasetResources) => void + readonly removeDataset: (target: ModelDatasetReference) => void +} + +type StereotypeCoordinator = Pick +type DatasetCoordinator = Pick + +/** + * Routes every authoring entry point through the project's existing + * coordinators, then keeps the browser's training and inference catalogs in + * step with successful dataset transactions. + */ +export class ProjectAuthoringService implements ProjectAuthoringOperations { + private tail: Promise = Promise.resolve() + + constructor( + private readonly stereotypes: StereotypeCoordinator, + private readonly datasets: DatasetCoordinator, + private readonly effects: ProjectAuthoringServiceEffects, + ) {} + + createStereotype(request: StereotypeAuthoringRequest): Promise { + return this.serialize(async () => { + const { generated } = await this.stereotypes.author(request) + return generated.modelPackage + }) + } + + deleteStereotype(target: ModelPackageReference): Promise { + return this.serialize(() => this.stereotypes.delete(target)) + } + + createDataset(request: DatasetAuthoringRequest): Promise { + return this.serialize(async () => { + const { generated } = await this.datasets.author(request) + this.effects.installDataset(generated) + return generated.modelDataset + }) + } + + updateDataset(target: ModelDatasetReference, request: DatasetAuthoringRequest): Promise { + return this.serialize(async () => { + const { generated } = await this.datasets.update(target, request) + this.effects.installDataset(generated) + }) + } + + deleteDataset(target: ModelDatasetReference): Promise { + return this.serialize(async () => { + await this.datasets.delete(target) + this.effects.removeDataset(target) + return target + }) + } + + private serialize(operation: () => Promise): Promise { + const result = this.tail.then(operation) + this.tail = result.then(() => undefined, () => undefined) + return result + } +} diff --git a/front-end/src/project-workspace/authoring.ts b/front-end/src/project-workspace/authoring.ts index ddde2ad9..e4c58432 100644 --- a/front-end/src/project-workspace/authoring.ts +++ b/front-end/src/project-workspace/authoring.ts @@ -1,10 +1,12 @@ -import type { DiagramCoreSnapshot, ModelManifest } from "../core/types" +import type { DiagramCoreSnapshot, ModelManifest, ModelPackageReference } from "../core/types" import { generateStereotypePackage, type GeneratedStereotypeResources, type StereotypeAuthoringRequest } from "../stereotype-authoring" import type { ModelBundleResources, PreparedModelScope } from "../type-system/editor-runtime" +import type { PackageExportInfo, PackageKey } from "../type-system/packages/types" import { ensureProjectPermission, normalizeProjectPath, type ProjectDirectoryHandle, + type ProjectFileHandle, type ProjectWorkspaceSession, writeProjectFiles, } from "./index" @@ -16,14 +18,15 @@ export type PreparedProjectScope = { /** The narrow Diagram seam needed by project-owned stereotype authoring. */ export interface ProjectAuthoringDiagram { - readonly modelManifest: ModelManifest + modelManifest: ModelManifest exportToJson(): string + packageExports(): ReadonlyMap prepareProjectScope(modelJson: string, modelBundle: ModelBundleResources): Promise - commitPreparedProjectScope(prepared: PreparedProjectScope): Promise + commitPreparedProjectScope(prepared: PreparedProjectScope, options?: { readonly preserveLiveGraph?: boolean }): Promise restoreProjectScope(modelJson: string, modelBundle: ModelBundleResources): Promise } -export type ProjectAuthoringPhase = "validation" | "scope" | "package-write" | "model-write" | "activation" | "rollback" +export type ProjectAuthoringPhase = "validation" | "scope" | "package-write" | "package-delete" | "model-write" | "activation" | "rollback" export class ProjectStereotypeAuthoringError extends Error { constructor( @@ -62,7 +65,6 @@ export type ProjectStereotypeAuthoringResult = { */ export class ProjectStereotypeAuthoringCoordinator { private resources: ModelBundleResources - private modelJson: string private tail: Promise = Promise.resolve() constructor( @@ -70,7 +72,6 @@ export class ProjectStereotypeAuthoringCoordinator { private readonly diagram: ProjectAuthoringDiagram, ) { this.resources = { ...session.resources } - this.modelJson = session.modelJson } author(request: StereotypeAuthoringRequest): Promise { @@ -79,10 +80,13 @@ export class ProjectStereotypeAuthoringCoordinator { return operation } + delete(target: ModelPackageReference): Promise { + const operation = this.tail.then(() => this.runDelete(target)) + this.tail = operation.then(() => undefined, () => undefined) + return operation + } + private async run(request: StereotypeAuthoringRequest): Promise { - // The session's initial modelJson is intentionally immutable. Graph - // autosaves may have advanced since startup, so author against the live - // DiagramCore snapshot and use that same snapshot for rollback. const previousModelJson = this.diagram.exportToJson() let generated: GeneratedStereotypeResources try { @@ -93,7 +97,14 @@ export class ProjectStereotypeAuthoringCoordinator { const packagePath = normalizeProjectPath(generated.modelPackage.path) const packagePrefix = `${packagePath}/` - if (this.diagram.modelManifest.customPackages.some((candidate) => ( + try { + await ensureProjectPermission(this.session.directory) + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "package-write", cause) + } + + const currentManifest = this.diagram.modelManifest + if (currentManifest.customPackages.some((candidate) => ( candidate.id === generated.modelPackage.id || candidate.path === packagePath ))) { throw new ProjectStereotypeAuthoringError( @@ -104,20 +115,11 @@ export class ProjectStereotypeAuthoringCoordinator { if (Object.keys(this.resources).some((path) => path === packagePath || path.startsWith(packagePrefix))) { throw new ProjectStereotypeAuthoringError(`Project package directory '${packagePath}' already exists`, "validation") } - try { - await ensureProjectPermission(this.session.directory) - } catch (cause) { - throw new ProjectStereotypeAuthoringError(messageOf(cause), "package-write", cause) - } - - const currentParsed = JSON.parse(previousModelJson) as Record - const currentManifest = this.diagram.modelManifest const nextManifest: ModelManifest = { ...currentManifest, customPackages: [...currentManifest.customPackages, generated.modelPackage], } - const nextProject = { ...currentParsed, manifest: nextManifest } - const nextModelJson = JSON.stringify(nextProject, null, 2) + let nextModelJson = withModelManifest(this.diagram.exportToJson(), nextManifest) const nextResources: ModelBundleResources = { ...this.resources, ...Object.fromEntries(Object.entries(generated.files).map(([path, value]) => [`${packagePrefix}${path}`, value])), @@ -132,6 +134,7 @@ export class ProjectStereotypeAuthoringCoordinator { const created = await createPackageDirectory(this.session.directory, packagePath) let modelWriteAttempted = false + let modelManifestInstalled = false let commitAttempted = false try { try { @@ -141,33 +144,181 @@ export class ProjectStereotypeAuthoringCoordinator { } try { modelWriteAttempted = true + this.diagram.modelManifest = nextManifest + modelManifestInstalled = true + // Include graph edits made while scope preparation and package I/O + // were awaiting; the Diagram commit also rebases at its boundary. + nextModelJson = withModelManifest(this.diagram.exportToJson(), nextManifest) await this.session.save(nextModelJson) } catch (cause) { throw new ProjectStereotypeAuthoringError(messageOf(cause), "model-write", cause) } try { commitAttempted = true - await this.diagram.commitPreparedProjectScope(prepared) + await this.diagram.commitPreparedProjectScope(prepared, { preserveLiveGraph: true }) } catch (cause) { throw new ProjectStereotypeAuthoringError(messageOf(cause), "activation", cause) } + const committedModelJson = this.diagram.exportToJson() + if (committedModelJson !== nextModelJson) { + await this.session.save(committedModelJson) + nextModelJson = committedModelJson + } } catch (operationError) { const rollbackErrors: unknown[] = [] + if (modelManifestInstalled) this.diagram.modelManifest = currentManifest + const rollbackModelJson = modelJsonForRollback(previousModelJson, this.diagram.exportToJson(), currentManifest) if (modelWriteAttempted) { - try { await this.session.save(previousModelJson) } catch (cause) { rollbackErrors.push(new Error(`model restore: ${messageOf(cause)}`)) } + try { await this.session.save(rollbackModelJson) } catch (cause) { rollbackErrors.push(new Error(`model restore: ${messageOf(cause)}`)) } } try { await removeCreatedPackageDirectory(created) } catch (cause) { rollbackErrors.push(new Error(`package removal: ${messageOf(cause)}`)) } if (commitAttempted) { - try { await this.diagram.restoreProjectScope(previousModelJson, this.resources) } catch (cause) { rollbackErrors.push(new Error(`runtime restore: ${messageOf(cause)}`)) } + try { await this.diagram.restoreProjectScope(rollbackModelJson, this.resources) } catch (cause) { rollbackErrors.push(new Error(`runtime restore: ${messageOf(cause)}`)) } } if (rollbackErrors.length > 0) throw new ProjectAuthoringRollbackError(operationError, new Error(rollbackErrors.map(messageOf).join("; "))) throw operationError } this.resources = nextResources - this.modelJson = nextModelJson return { generated, modelJson: nextModelJson } } + + private async runDelete(target: ModelPackageReference): Promise { + const initialManifest = this.diagram.modelManifest + const initialTarget = initialManifest.customPackages.find((candidate) => samePackageIdentity(candidate, target)) + if (!initialTarget) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${target.id}@${target.version}' at '${target.path}' is not owned by the active project`, + "validation", + ) + } + if (graphUsesPackage(this.diagram.exportToJson(), initialTarget)) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${initialTarget.id}@${initialTarget.version}' is used by the project graph`, + "validation", + ) + } + if (isRequiredByAnotherPackage(this.diagram.packageExports(), initialTarget)) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${initialTarget.id}@${initialTarget.version}' is required by another project stereotype`, + "validation", + ) + } + if (!this.session.directory.removeEntry) { + throw new ProjectStereotypeAuthoringError("The browser cannot remove project stereotype directories", "package-delete") + } + + let directory: ProjectDirectoryHandle + let previousPackageResources: Record + let previousPackageDirectories: string[] + try { + await ensureProjectPermission(this.session.directory) + directory = await openPackageDirectory(this.session.directory, initialTarget.path) + const snapshot = await readPackageDirectory(directory, initialTarget.path) + previousPackageResources = snapshot.resources + previousPackageDirectories = snapshot.directories + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "package-delete", cause) + } + + const previousModelJson = this.diagram.exportToJson() + const currentManifest = this.diagram.modelManifest + const owned = currentManifest.customPackages.find((candidate) => samePackageIdentity(candidate, target)) + if (!owned) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${target.id}@${target.version}' is no longer owned by the active project`, + "validation", + ) + } + if (graphUsesPackage(previousModelJson, owned)) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${owned.id}@${owned.version}' is used by the project graph`, + "validation", + ) + } + if (isRequiredByAnotherPackage(this.diagram.packageExports(), owned)) { + throw new ProjectStereotypeAuthoringError( + `Stereotype '${owned.id}@${owned.version}' is required by another project stereotype`, + "validation", + ) + } + + const prefix = `${owned.path}/` + const nextResources = Object.fromEntries( + Object.entries(this.resources).filter(([path]) => !path.startsWith(prefix)), + ) + const nextPackages = currentManifest.customPackages.filter((candidate) => !samePackageIdentity(candidate, owned)) + const nextManifest: ModelManifest = { ...currentManifest, customPackages: nextPackages } + let nextModelJson = withModelManifest(previousModelJson, nextManifest) + + let prepared: PreparedProjectScope + try { + prepared = await this.diagram.prepareProjectScope(nextModelJson, nextResources) + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "scope", cause) + } + + const parentPath = owned.path.split("/").slice(0, -1).join("/") + const directoryName = owned.path.split("/").pop()! + let modelWriteAttempted = false + let directoryRemovalAttempted = false + let modelManifestInstalled = false + let commitAttempted = false + try { + try { + modelWriteAttempted = true + this.diagram.modelManifest = nextManifest + modelManifestInstalled = true + nextModelJson = withModelManifest(this.diagram.exportToJson(), nextManifest) + await this.session.save(nextModelJson) + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "model-write", cause) + } + try { + directoryRemovalAttempted = true + const parent = parentPath ? await openPackageDirectory(this.session.directory, parentPath) : this.session.directory + if (!parent.removeEntry) throw new Error("The browser cannot remove project stereotype directories") + await parent.removeEntry(directoryName, { recursive: true }) + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "package-delete", cause) + } + try { + commitAttempted = true + await this.diagram.commitPreparedProjectScope(prepared, { preserveLiveGraph: true }) + } catch (cause) { + throw new ProjectStereotypeAuthoringError(messageOf(cause), "activation", cause) + } + const committedModelJson = this.diagram.exportToJson() + if (committedModelJson !== nextModelJson) { + await this.session.save(committedModelJson) + nextModelJson = committedModelJson + } + } catch (operationError) { + const rollbackErrors: unknown[] = [] + if (modelManifestInstalled) this.diagram.modelManifest = currentManifest + const rollbackModelJson = modelJsonForRollback(previousModelJson, this.diagram.exportToJson(), currentManifest) + if (directoryRemovalAttempted) { + try { + await restorePackageDirectory(this.session.directory, owned.path, previousPackageDirectories, previousPackageResources) + } catch (cause) { + rollbackErrors.push(new Error(`package restore: ${messageOf(cause)}`)) + } + } + if (modelWriteAttempted) { + try { await this.session.save(rollbackModelJson) } catch (cause) { rollbackErrors.push(new Error(`model restore: ${messageOf(cause)}`)) } + } + if (commitAttempted) { + const previousResources = { ...this.resources, ...previousPackageResources } + try { await this.diagram.restoreProjectScope(rollbackModelJson, previousResources) } + catch (cause) { rollbackErrors.push(new Error(`runtime restore: ${messageOf(cause)}`)) } + } + if (rollbackErrors.length > 0) throw new ProjectAuthoringRollbackError(operationError, new Error(rollbackErrors.map(messageOf).join("; "))) + throw operationError + } + + this.resources = nextResources + return owned + } } type CreatedPackageDirectory = { @@ -202,6 +353,138 @@ async function removeCreatedPackageDirectory(created: CreatedPackageDirectory): await created.parent.removeEntry(created.name, { recursive: true }) } +async function openPackageDirectory(root: ProjectDirectoryHandle, path: string): Promise { + let directory = root + for (const part of normalizeProjectPath(path).split("/")) directory = await directory.getDirectoryHandle(part) + return directory +} + +async function readPackageDirectory( + directory: ProjectDirectoryHandle, + projectPath: string, +): Promise<{ readonly resources: Record; readonly directories: string[] }> { + const resources: Record = {} + const directories: string[] = [] + await readPackageEntries(directory, projectPath, resources, directories) + return { resources, directories } +} + +async function readPackageEntries( + directory: ProjectDirectoryHandle, + prefix: string, + resources: Record, + directories: string[], +): Promise { + const entries = directory.entries ? directory.entries() : directory.values ? namedEntries(directory.values()) : undefined + if (!entries) throw new Error("Directory handle does not support recursive enumeration") + for await (const [name, handle] of entries) { + const path = normalizeProjectPath(`${prefix}/${name}`) + if (isProjectDirectory(handle)) { + directories.push(path) + await readPackageEntries(handle, path, resources, directories) + } else { + const file = await (handle as ProjectFileHandle).getFile() + // Prefer bytes because File.text() would corrupt arbitrary binary assets + // when a failed deletion needs to restore the exact package contents. + if (file.arrayBuffer) resources[path] = new Uint8Array(await file.arrayBuffer()) + else if (file.text) resources[path] = await file.text() + else throw new Error(`Project file '${path}' cannot be read`) + } + } +} + +async function* namedEntries( + values: AsyncIterable, +): AsyncIterable<[string, ProjectDirectoryHandle | ProjectFileHandle]> { + for await (const handle of values) { + if (!handle.name) throw new Error("File system entry has no name") + yield [handle.name, handle] + } +} + +function isProjectDirectory(handle: ProjectDirectoryHandle | ProjectFileHandle): handle is ProjectDirectoryHandle { + return handle.kind === "directory" || (handle.kind === undefined && ("entries" in handle || "values" in handle)) +} + +async function restorePackageDirectory( + root: ProjectDirectoryHandle, + path: string, + directories: readonly string[], + resources: Readonly>, +): Promise { + const packageDirectory = await createPackageDirectoryForRestore(root, path) + for (const directoryPath of directories) { + await openOrCreatePackageDirectory(root, directoryPath) + } + const prefix = `${path}/` + const files = Object.fromEntries(Object.entries(resources) + .filter(([resourcePath]) => resourcePath.startsWith(prefix)) + .map(([resourcePath, value]) => [resourcePath.slice(prefix.length), value])) + await writeProjectFiles(packageDirectory, files) +} + +async function createPackageDirectoryForRestore(root: ProjectDirectoryHandle, path: string): Promise { + const segments = normalizeProjectPath(path).split("/") + const name = segments.pop()! + let parent = root + for (const segment of segments) parent = await openOrCreateChildDirectory(parent, segment) + return openOrCreateChildDirectory(parent, name) +} + +async function openOrCreatePackageDirectory(root: ProjectDirectoryHandle, path: string): Promise { + let directory = root + for (const part of normalizeProjectPath(path).split("/")) directory = await openOrCreateChildDirectory(directory, part) + return directory +} + +async function openOrCreateChildDirectory(parent: ProjectDirectoryHandle, name: string): Promise { + try { return await parent.getDirectoryHandle(name) } + catch (cause) { + if (!isNotFoundError(cause)) throw cause + return parent.getDirectoryHandle(name, { create: true }) + } +} + +function graphUsesPackage(modelJson: string, target: ModelPackageReference): boolean { + const project = JSON.parse(modelJson) as { readonly nodes?: unknown } + if (!Array.isArray(project.nodes)) return false + return project.nodes.some((value) => { + if (!value || typeof value !== "object") return false + const node = value as { readonly data?: { readonly package?: { readonly id?: unknown; readonly version?: unknown } } } + return node.data?.package?.id === target.id && node.data.package.version === target.version + }) +} + +function withModelManifest(modelJson: string, manifest: ModelManifest): string { + const project = JSON.parse(modelJson) as Record + return JSON.stringify({ ...project, manifest }, null, 2) +} + +function modelJsonForRollback(previousModelJson: string, liveModelJson: string, manifest: ModelManifest): string { + const previous = JSON.parse(previousModelJson) as Record + const live = JSON.parse(liveModelJson) as Record + const graphUnchanged = JSON.stringify(previous.nodes ?? []) === JSON.stringify(live.nodes ?? []) && + JSON.stringify(previous.edges ?? []) === JSON.stringify(live.edges ?? []) + if (graphUnchanged) return previousModelJson + return JSON.stringify({ ...previous, nodes: live.nodes ?? [], edges: live.edges ?? [], manifest }, null, 2) +} + +function isRequiredByAnotherPackage( + packageExports: ReadonlyMap, + target: ModelPackageReference, +): boolean { + const targetKey: PackageKey = `${target.id}@${target.version}` + for (const [candidateKey, candidate] of packageExports) { + if (candidateKey === targetKey) continue + if (Object.values(candidate.resolvedDependencies ?? {}).includes(targetKey)) return true + } + return false +} + +function samePackageIdentity(left: ModelPackageReference, right: ModelPackageReference): boolean { + return left.id === right.id && left.version === right.version && left.path === right.path +} + function isNotFoundError(cause: unknown): boolean { if (!cause || typeof cause !== "object") return false const error = cause as { name?: string; code?: number | string; message?: string } diff --git a/front-end/src/sync/BrowserRPCHandler.ts b/front-end/src/sync/BrowserRPCHandler.ts index 33b646d1..60a8b258 100644 --- a/front-end/src/sync/BrowserRPCHandler.ts +++ b/front-end/src/sync/BrowserRPCHandler.ts @@ -21,6 +21,7 @@ // | { id: string, error: { message: string } } import type { Diagram } from "../Diagram.svelte"; +import type { ModelPackageReference } from "../core/types"; import type { Node, Edge } from "@xyflow/svelte"; import type { GraphInferenceResult } from "../type-system/graph/types"; import { packageIdentity } from "../type-system/graph/types"; @@ -28,7 +29,10 @@ import { compileGraphBindings } from "../type-system/graph/bindings"; import { initialPackageParameters, validatePackageParameterValues } from "../type-system/editor/package-ui"; import { TrainingController } from "../training/controller"; import type { ProjectPathPayload } from "../project-workspace/path"; -import type { DatasetParameterValue } from "../project-workspace/dataset-contract"; +import type { DatasetParameterValue, ModelDatasetReference } from "../project-workspace/dataset-contract"; +import type { DatasetAuthoringRequest } from "../project-workspace/dataset-authoring"; +import type { ProjectAuthoringOperations } from "../project-workspace/authoring-service"; +import type { StereotypeAuthoringRequest } from "../stereotype-authoring"; // ── RPC Types ────────────────────────────────────────────────────────── @@ -124,6 +128,7 @@ export class BrowserRPCHandler { private viewport?: ViewportController; private training?: TrainingController; private project?: ProjectRPCBridge; + private authoring?: ProjectAuthoringOperations; private readonly pendingBrowserRequests = new Map(); private nextBrowserRequestId = 0; @@ -136,7 +141,14 @@ export class BrowserRPCHandler { * @param viewport Optional viewport controller (fitView/setCenter). * Passed from FlowCanvas.svelte via useSvelteFlow(). */ - constructor(diagram: Diagram | undefined, url?: string, viewport?: ViewportController, training?: TrainingController, project?: ProjectRPCBridge) { + constructor( + diagram: Diagram | undefined, + url?: string, + viewport?: ViewportController, + training?: TrainingController, + project?: ProjectRPCBridge, + authoring?: ProjectAuthoringOperations, + ) { this.diagram = diagram as Diagram; this.diagramActive = diagram !== undefined; this.url = @@ -147,6 +159,7 @@ export class BrowserRPCHandler { this.viewport = viewport; this.training = training; this.project = project; + this.authoring = authoring; } bindDiagram(diagram: Diagram | undefined): void { @@ -154,6 +167,10 @@ export class BrowserRPCHandler { if (diagram) this.diagram = diagram; } + bindAuthoringService(authoring: ProjectAuthoringOperations | undefined): void { + this.authoring = authoring; + } + /** Send a fire-and-forget browser-owned notification to the MCP bridge. */ notify(method: string, params: Record): void { if (this.ws?.readyState === WEBSOCKET_OPEN) this.ws.send(JSON.stringify({ method, params })); @@ -304,6 +321,20 @@ export class BrowserRPCHandler { result = this.handleGetPackageDiagnostics(); break; + // ── Project authoring ──────────────────────────────────── + case "create_stereotype": + result = this.requireAuthoringService().createStereotype(params as unknown as StereotypeAuthoringRequest); + break; + case "delete_stereotype": + result = this.requireAuthoringService().deleteStereotype(projectPackageIdentity(params)); + break; + case "create_dataset": + result = this.requireAuthoringService().createDataset(decodeDatasetAuthoringRequest(params)); + break; + case "delete_dataset": + result = this.requireAuthoringService().deleteDataset(projectDatasetIdentity(params)); + break; + // ── Mutations ───────────────────────────────────────────── case "create_node": result = this.handleCreateNode(params); @@ -466,6 +497,11 @@ export class BrowserRPCHandler { return this.training; } + private requireAuthoringService(): ProjectAuthoringOperations { + if (!this.authoring) throw Object.assign(new Error("Project authoring service unavailable for this editor"), { code: "PROJECT_AUTHORING_UNAVAILABLE" }); + return this.authoring; + } + private syncDatasetInference(): void { const training = this.training; if (!training) return; @@ -1192,3 +1228,58 @@ export class BrowserRPCHandler { }; } } + +function projectPackageIdentity(params: unknown): ModelPackageReference { + return projectResourceIdentity(params, "stereotype") +} + +function projectDatasetIdentity(params: unknown): ModelDatasetReference { + return projectResourceIdentity(params, "dataset") +} + +function projectResourceIdentity( + value: unknown, + resource: "stereotype" | "dataset", +): T { + if (!isRecord(value)) throw new Error(`${resource} identity must be an object`) + for (const key of ["id", "version", "path"] as const) { + if (typeof value[key] !== "string" || value[key].length === 0) { + throw new Error(`${resource} identity '${key}' must be a non-empty string`) + } + } + return { id: value.id as string, version: value.version as string, path: value.path as string } as T +} + +function decodeDatasetAuthoringRequest(value: unknown): DatasetAuthoringRequest { + if (!isRecord(value)) throw new Error("dataset authoring request must be an object") + if (value.dataFiles === undefined) return value as unknown as DatasetAuthoringRequest + if (!Array.isArray(value.dataFiles)) throw new Error("dataset dataFiles must be an array") + const dataFiles = value.dataFiles.map((entry, index) => { + if (!isRecord(entry)) throw new Error(`dataset data file ${index} must be an object`) + if (typeof entry.path !== "string") throw new Error(`dataset data file ${index} path must be a string`) + if (typeof entry.dataBase64 !== "string") throw new Error(`dataset data file ${index} dataBase64 must be a string`) + return { path: entry.path, bytes: decodeStrictBase64(entry.dataBase64) } + }) + return { ...value, dataFiles } as unknown as DatasetAuthoringRequest +} + +const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/ + +function decodeStrictBase64(value: string): Uint8Array { + if (!BASE64.test(value)) throw new Error("dataset data file dataBase64 must be canonical base64") + let binary: string + try { + binary = atob(value) + } catch { + throw new Error("dataset data file dataBase64 must be canonical base64") + } + const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0)) + let encodedBytes = "" + for (const byte of bytes) encodedBytes += String.fromCharCode(byte) + if (btoa(encodedBytes) !== value) throw new Error("dataset data file dataBase64 must be canonical base64") + return bytes +} + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value) +} diff --git a/front-end/src/type-system/editor-runtime.ts b/front-end/src/type-system/editor-runtime.ts index d9714816..004cc910 100644 --- a/front-end/src/type-system/editor-runtime.ts +++ b/front-end/src/type-system/editor-runtime.ts @@ -3,7 +3,7 @@ import type { DatasetDefinition } from "../project-workspace/dataset-contract" import { PackageGraphScheduler } from "./graph/scheduler" import { TypeSystemHost, type ActivePackageMetadata, type PackageSelection } from "./host" import { bundledCoreRecords } from "./bundled/catalog" -import { PackageCatalog, packageKey, packageRecordKey } from "./packages/catalog" +import { immutableRecord, PackageCatalog, packageKey, packageRecordKey } from "./packages/catalog" import type { InstalledPackageRecord, PackageExportInfo, PackageKey, PackageSource } from "./packages/types" import { parseModelManifest, type ModelManifest, type PackageIdentity } from "../core/types" import { parseDefinition, parseManifest } from "./packages/validation" @@ -226,7 +226,7 @@ export class EditorTypeSystemRuntime { graphIdentities: readonly RuntimePackageIdentity[] = [], ): Promise { const manifest = parseModelManifest(manifestValue) - const customPackages = await resolveModelPackageRecords(manifest, bundle) + const customPackages = await resolveModelPackageRecords(manifest, bundle, this.bundled) const catalog = PackageCatalog.composeModel(this.bundled, customPackages) const host = await TypeSystemHost.create(catalog.records().map((record) => ({ resources: record.resources }))) const coordinator = new PackageActivationCoordinator(host, catalog) @@ -299,6 +299,7 @@ export class EditorTypeSystemRuntime { export async function resolveModelPackageRecords( manifest: ModelManifest, bundle: ModelBundleResources | undefined, + bundled: readonly InstalledPackageRecord[] = [], ): Promise { if (manifest.customPackages.length > 0 && bundle === undefined) { throw new Error(`model '${manifest.id}' declares custom packages but no model bundle was provided`) @@ -335,7 +336,11 @@ export async function resolveModelPackageRecords( resources, })) } - return records + const resolver = PackageCatalog.composeModel(bundled, records) + return records.map((record) => immutableRecord({ + ...record, + resolvedDependencies: resolver.resolveDependencies(record.key), + })) } function decodeModelResource(value: string | Uint8Array): string { diff --git a/mcp-server/__tests__/authoring-tools.test.ts b/mcp-server/__tests__/authoring-tools.test.ts new file mode 100644 index 00000000..aa3d0285 --- /dev/null +++ b/mcp-server/__tests__/authoring-tools.test.ts @@ -0,0 +1,128 @@ +import { describe, expect, it, vi } from "vitest" +import type { ServerContext } from "../src/server" +import type { BrowserRPCClient } from "../src/browser-client" +import * as authoringTools from "../src/tools/authoring" +import { z } from "zod" + +function createContext() { + const call = vi.fn().mockResolvedValue({ status: "ok" }) + const ctx = { browser: { call } as unknown as BrowserRPCClient } as ServerContext + return { ctx, call } +} + +async function invoke( + tool: { schema: S; handler(ctx: ServerContext, input: z.infer): Promise }, + ctx: ServerContext, + input: unknown, +) { + return tool.handler(ctx, tool.schema.parse(input)) +} + +describe("project authoring tools", () => { + it("exports exactly the four auto-discoverable authoring tools", () => { + expect(Object.keys(authoringTools).sort()).toEqual([ + "create_dataset", + "create_stereotype", + "delete_dataset", + "delete_stereotype", + ]) + for (const tool of Object.values(authoringTools)) { + expect(tool.schema).toBeDefined() + expect(tool.handler).toBeTypeOf("function") + } + }) + + it("forwards the complete stereotype form request and returns the browser result", async () => { + const { ctx, call } = createContext() + const request = { + id: "example.loss", + version: "0.1.0", + directory: "packages/example-loss", + name: "Example loss", + description: "A project-owned loss", + kind: "loss", + view: { color: "#123456", width: 180, height: 72 }, + dependencies: { "example.base": "^1.0.0" }, + parameters: [{ + name: "reduction", + definition: { type: "string", choices: ["mean", "sum"], default: "mean", position: "bottom" }, + }], + objective: { externalInputs: [{ name: "target", source: "batch.targets.target", transform: "flatten_batch" }] }, + } + const browserResult = { id: request.id, version: request.version, path: request.directory } + call.mockResolvedValue(browserResult) + + await expect(invoke(authoringTools.create_stereotype, ctx, request)).resolves.toEqual(browserResult) + expect(call).toHaveBeenCalledWith("create_stereotype", request) + }) + + it("forwards dataset semantic fields and strict base64 file transport unchanged", async () => { + const { ctx, call } = createContext() + const request = { + id: "example.dataset", + version: "1.2.0", + directory: "datasets/example-dataset", + name: "Example dataset", + description: "Tiny fixture", + parameters: [{ name: "batch_size", type: "integer", required: true, default: 8 }], + inputs: [{ name: "features", shape: ["B", 4], dtype: "float32" }], + targets: [{ name: "labels", shape: ["B"], dtype: "int64" }], + classes: { count: 2, names: ["negative", "positive"] }, + dataFiles: [{ path: "train.bin", dataBase64: "AAEC" }], + } + + await invoke(authoringTools.create_dataset, ctx, request) + expect(call).toHaveBeenCalledWith("create_dataset", request) + }) + + it("proxies a valid dataset identity to the selected browser tab", async () => { + const { ctx, call } = createContext() + const request = { id: "example.dataset", version: "1.2.0", path: "datasets/example-dataset" } + await invoke(authoringTools.delete_dataset, ctx, request) + expect(call).toHaveBeenCalledWith("delete_dataset", request) + }) + + it("proxies a valid stereotype identity to the selected browser tab", async () => { + const { ctx, call } = createContext() + const request = { id: "example.layer", version: "0.1.0", path: "packages/example-layer" } + await invoke(authoringTools.delete_stereotype, ctx, request) + expect(call).toHaveBeenCalledWith("delete_stereotype", request) + }) + + it.each(["AAE", "AA?=", "Zh=="])("rejects malformed or non-canonical base64 (%s) before browser RPC", async (dataBase64) => { + const { ctx, call } = createContext() + const request = { + id: "example.dataset", + version: "1.2.0", + directory: "datasets/example-dataset", + name: "Example dataset", + parameters: [], + inputs: [], + targets: [], + dataFiles: [{ path: "train.bin", dataBase64 }], + } + + await expect(invoke(authoringTools.create_dataset, ctx, request)).rejects.toThrow() + expect(call).not.toHaveBeenCalled() + }) + + it.each([ + { id: 42, version: "1.0.0", path: "datasets/example" }, + { id: "example.dataset", version: "1.0.0" }, + { id: "example.dataset", version: "1.0.0", path: "datasets/example", name: "display name" }, + ])("rejects malformed or non-exact delete identity before browser RPC", async (identity) => { + const { ctx, call } = createContext() + await expect(invoke(authoringTools.delete_dataset, ctx, identity)).rejects.toThrow() + expect(call).not.toHaveBeenCalled() + }) + + it("leaves browser/domain errors visible to the MCP caller", async () => { + const { ctx, call } = createContext() + call.mockRejectedValue(new Error("stereotype is required by another package")) + const request = { id: "example.layer", version: "0.1.0", path: "packages/example-layer" } + + await expect(invoke(authoringTools.delete_stereotype, ctx, request)).rejects.toThrow( + "stereotype is required by another package", + ) + }) +}) diff --git a/mcp-server/src/server.ts b/mcp-server/src/server.ts index c793e271..fce899aa 100644 --- a/mcp-server/src/server.ts +++ b/mcp-server/src/server.ts @@ -51,6 +51,7 @@ import * as connectionTools from "./tools/connection.js"; import * as screenshotTools from "./tools/screenshot.js"; import * as remoteTrainingTools from "./tools/remote-training.js"; import * as projectTools from "./tools/project.js"; +import * as authoringTools from "./tools/authoring.js"; import { applyProjectResource, type ProjectResourceOperation } from "./project-path.js"; // ── ServerContext ─────────────────────────────────────────────────────── @@ -180,6 +181,7 @@ export async function createServer( screenshotTools, remoteTrainingTools, projectTools, + authoringTools, ] as Record[]; for (const module of allToolModules) { diff --git a/mcp-server/src/tools/authoring.ts b/mcp-server/src/tools/authoring.ts new file mode 100644 index 00000000..884490b1 --- /dev/null +++ b/mcp-server/src/tools/authoring.ts @@ -0,0 +1,156 @@ +import { z } from "zod" +import type { ServerContext } from "../server.js" + +const packageKind = z.enum(["input", "layer", "loss", "join", "subflow", "output"]) +const dtype = z.enum([ + "float16", "bfloat16", "float32", "float64", + "int8", "uint8", "int16", "int32", "int64", "bool", +]) +const dimension = z.union([z.string(), z.number().finite()]) +const jsonValue: z.ZodType = z.lazy(() => z.union([ + z.null(), + z.boolean(), + z.number().finite(), + z.string(), + z.array(jsonValue), + z.record(z.string(), jsonValue), +])) + +type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue } + +const listItemDefinition = z.discriminatedUnion("type", [ + z.object({ type: z.literal("integer"), minimum: z.number().optional(), maximum: z.number().optional(), default: z.number().int().optional() }).strict(), + z.object({ type: z.literal("number"), minimum: z.number().optional(), maximum: z.number().optional(), default: z.number().optional() }).strict(), + z.object({ type: z.literal("boolean"), default: z.boolean().optional() }).strict(), + z.object({ type: z.literal("string"), choices: z.array(z.string()).optional(), default: z.string().optional() }).strict(), +]) + +const parameterDefinition = z.discriminatedUnion("type", [ + z.object({ type: z.literal("integer"), minimum: z.number().optional(), maximum: z.number().optional(), default: z.number().int().optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ type: z.literal("number"), minimum: z.number().optional(), maximum: z.number().optional(), default: z.number().optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ type: z.literal("boolean"), default: z.boolean().optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ type: z.literal("string"), choices: z.array(z.string()).optional(), default: z.string().optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ type: z.literal("dtype"), choices: z.array(dtype), default: dtype.optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ type: z.literal("shape"), default: z.array(dimension).optional(), position: z.enum(["top", "bottom"]) }).strict(), + z.object({ + type: z.literal("list"), + items: listItemDefinition, + minItems: z.number().optional(), + maxItems: z.number().optional(), + default: z.array(jsonValue).optional(), + position: z.enum(["top", "bottom"]), + }).strict(), + z.object({ + type: z.literal("stereotype"), + kind: packageKind, + default: z.object({ + id: z.string().min(1), + version: z.string().min(1), + parameters: z.record(z.string(), jsonValue), + }).strict().optional(), + position: z.enum(["top", "bottom"]), + }).strict(), +]) + +const stereotypeAuthoringRequest = z.object({ + id: z.string().min(1), + version: z.string().min(1), + directory: z.string().min(1), + name: z.string().min(1), + description: z.string().optional(), + kind: packageKind, + view: z.object({ + color: z.string(), + width: z.number(), + height: z.number(), + }).strict(), + dependencies: z.record(z.string(), z.string()).optional(), + parameters: z.array(z.object({ + name: z.string().min(1), + definition: parameterDefinition, + }).strict()), + objective: z.object({ + externalInputs: z.array(z.object({ + name: z.string(), + source: z.string(), + transform: z.enum(["flatten_batch"]).optional(), + }).strict()), + }).strict().optional(), +}).strict() + +const datasetParameter = z.discriminatedUnion("type", [ + z.object({ name: z.string(), type: z.literal("string"), required: z.boolean(), default: z.string().optional() }).strict(), + z.object({ name: z.string(), type: z.literal("integer"), required: z.boolean(), default: z.number().int().optional() }).strict(), + z.object({ name: z.string(), type: z.literal("number"), required: z.boolean(), default: z.number().optional() }).strict(), + z.object({ name: z.string(), type: z.literal("boolean"), required: z.boolean(), default: z.boolean().optional() }).strict(), +]) + +const datasetSlot = z.object({ + name: z.string(), + shape: z.array(dimension), + dtype, +}).strict() + +const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/ + +const isCanonicalBase64 = (value: string): boolean => { + if (!BASE64.test(value)) return false + return Buffer.from(value, "base64").toString("base64") === value +} + +const datasetAuthoringRequest = z.object({ + id: z.string().min(1), + version: z.string().min(1), + directory: z.string().min(1), + name: z.string().min(1), + description: z.string().optional(), + parameters: z.array(datasetParameter), + inputs: z.array(datasetSlot), + targets: z.array(datasetSlot), + classes: z.object({ + count: z.number().int(), + names: z.array(z.string()).optional(), + }).strict().optional(), + dataFiles: z.array(z.object({ + path: z.string().min(1), + dataBase64: z.string().regex(BASE64, "must use standard base64").refine(isCanonicalBase64, "must be canonical standard base64"), + }).strict()).optional(), +}).strict() + +const resourceIdentity = z.object({ + id: z.string().min(1), + version: z.string().min(1), + path: z.string().min(1), +}).strict() + +/** Create a project-owned stereotype through the selected browser's authoring coordinator. */ +export const create_stereotype = { + schema: stereotypeAuthoringRequest, + async handler(ctx: ServerContext, input: z.infer) { + return ctx.browser.call("create_stereotype", input) + }, +} + +/** Delete exactly one project-owned stereotype; ownership and eligibility stay browser-owned. */ +export const delete_stereotype = { + schema: resourceIdentity, + async handler(ctx: ServerContext, input: z.infer) { + return ctx.browser.call("delete_stereotype", input) + }, +} + +/** Create a project-owned dataset; optional file bytes cross JSON as canonical base64. */ +export const create_dataset = { + schema: datasetAuthoringRequest, + async handler(ctx: ServerContext, input: z.infer) { + return ctx.browser.call("create_dataset", input) + }, +} + +/** Delete exactly one project-owned dataset; backend archives and jobs are untouched by this proxy. */ +export const delete_dataset = { + schema: resourceIdentity, + async handler(ctx: ServerContext, input: z.infer) { + return ctx.browser.call("delete_dataset", input) + }, +}