@istar-ts/actions 0.15.0-beta.0 → 0.15.0-beta.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AnyIstarModel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
+import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
@@ -216,8 +216,35 @@ export interface UpdateLinkDisplayOperation extends Operation {
   readonly linkId: string;
   readonly patch: Readonly<Record<string, unknown>>;
 }
+/**
+ * Changes the kind of a set of links: each listed link's id, source, target, order in the file,
+ * name, value, custom properties and display are kept; other links are untouched. One undo step
+ * for the whole set, all or nothing. A link whose kind is already `elementTypeId` is a no-op;
+ * an empty `linkIds` is a no-op too. Rejected (model untouched) if `canLink` refuses any listed
+ * link's new kind for its unchanged source and target (e.g. a mixed-refinement rule), or if the
+ * link keeps a `value` the new kind's `possibleLabels` disallows.
+ */
+export interface ChangeLinkKindOperation<LK extends string = LinkKind> extends Operation {
+  readonly kind: "istar.changeLinkKind";
+  readonly linkIds: readonly string[];
+  /** The links' new kind, e.g. `istar.OrRefinementLink`. */
+  readonly elementTypeId: LK;
+}
+/**
+ * Sets (or, with `null` or an empty block, removes) the model file's own `"metamodel"` block:
+ * custom element kinds, groupers, link kinds with their rules and line style (`withFileMetamodel`
+ * in `@istar-ts/core`). One undo step; undo restores the previous block exactly. Rejected (model
+ * untouched) if the block is malformed, collides with the host's kinds, or drops a kind an
+ * element or link still uses. A host's dialect-specific checks (e.g. goal-controller's own
+ * validation of the block) run as an `ActionGuard` on this operation's kind, so their refusal
+ * also comes back as diagnostics.
+ */
+export interface SetFileMetamodelOperation extends Operation {
+  readonly kind: "istar.setFileMetamodel";
+  readonly block: FileMetamodel | null;
+}
 /** Every operation, keyed by `kind`. */
-export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation;
+export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation;
 export interface RequestModelAction extends RequestAction {
   readonly kind: "requestModel";
   readonly options?: Args;
@@ -477,10 +504,28 @@ export interface ActionDispatcher<EK extends string = ElementKind, LK extends st
  * the operation; others are returned with the result.
  */
 export type ActionGuard<EK extends string = ElementKind, LK extends string = LinkKind> = (operation: IstarOperation<EK, LK>, model: IstarModel<EK, LK>) => readonly GoalDiagnostic[] | void;
+/**
+ * A host's rule, run after each operation is applied (and after each operation of a compound
+ * one, plus once more on the compound's own result), inside the operation's transaction. Sees
+ * the model as the operation leaves it (`modelAfter`) and as it was before (`modelBefore`), so
+ * it can check things a pre-guard can't without re-applying the operation itself (goal-controller's
+ * edgeV2 engine check is the motivating case). Diagnostics of severity `error` roll the
+ * transaction back: the model is untouched and there is no undo entry. Others are returned with
+ * the result, merged with pre-guards' warnings.
+ */
+export type ActionPostGuard<EK extends string = ElementKind, LK extends string = LinkKind> = (operation: IstarOperation<EK, LK>, modelAfter: IstarModel<EK, LK>, modelBefore: IstarModel<EK, LK>) => readonly GoalDiagnostic[] | void;
 export interface ActionDispatcherOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
   readonly guards?: readonly ActionGuard<EK, LK>[];
-  /** What `RequestContextActions` offers. Default: `DEFAULT_PALETTE` (iStar 2.0's). */
-  readonly palette?: AnyPaletteDescription;
+  /** Run after each operation is applied; see `ActionPostGuard`. */
+  readonly postGuards?: readonly ActionPostGuard<EK, LK>[];
+  /**
+   * What `RequestContextActions` offers: a fixed description, or a function evaluated on each
+   * request (so a host can track a registry or extensions that change after this dispatcher was
+   * created — a plain `AnyPaletteDescription` is read once, at creation). Default: derived from
+   * the model's current metamodel (`paletteFromMetamodel`), the same fallback `contributionFor`
+   * (`@istar-ts/glsp`) uses — not iStar 2.0's palette regardless of dialect.
+   */
+  readonly palette?: AnyPaletteDescription | (() => AnyPaletteDescription);
   /**
    * Property schemas an operation must not break: an operation that adds an issue
    * (`validateModelProperties`) is rejected. Their issues are also markers.
@@ -527,6 +572,15 @@ export declare function typeHintsFor<EK extends string, LK extends string>(metam
  * lacks are left out.
  */
 export declare function contextActionsFor<EK extends string, LK extends string>(palette: AnyPaletteDescription, metamodel: Metamodel<EK, LK>): Pick<SetContextActions, "actions" | "groups">;
+/**
+ * A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+ * (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+ * an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+ * hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+ * `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+ * was given.
+ */
+export declare function paletteFromMetamodel(metamodel: AnyMetamodel): AnyPaletteDescription;
 //#endregion
 //#region src/host.d.ts
 /** A host's knowledge for the model: a system-prompt section and/or an MCP resource. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyIstarModel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
+import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, DiagnosticSeverity, ElementKind, FileMetamodel, GoalDiagnostic, IstarModel, LinkKind, Metamodel, ModelChange, ModelStore, PistarFile, PropertySchema, PropertyShape } from "@istar-ts/core";
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
@@ -216,8 +216,35 @@ export interface UpdateLinkDisplayOperation extends Operation {
   readonly linkId: string;
   readonly patch: Readonly<Record<string, unknown>>;
 }
+/**
+ * Changes the kind of a set of links: each listed link's id, source, target, order in the file,
+ * name, value, custom properties and display are kept; other links are untouched. One undo step
+ * for the whole set, all or nothing. A link whose kind is already `elementTypeId` is a no-op;
+ * an empty `linkIds` is a no-op too. Rejected (model untouched) if `canLink` refuses any listed
+ * link's new kind for its unchanged source and target (e.g. a mixed-refinement rule), or if the
+ * link keeps a `value` the new kind's `possibleLabels` disallows.
+ */
+export interface ChangeLinkKindOperation<LK extends string = LinkKind> extends Operation {
+  readonly kind: "istar.changeLinkKind";
+  readonly linkIds: readonly string[];
+  /** The links' new kind, e.g. `istar.OrRefinementLink`. */
+  readonly elementTypeId: LK;
+}
+/**
+ * Sets (or, with `null` or an empty block, removes) the model file's own `"metamodel"` block:
+ * custom element kinds, groupers, link kinds with their rules and line style (`withFileMetamodel`
+ * in `@istar-ts/core`). One undo step; undo restores the previous block exactly. Rejected (model
+ * untouched) if the block is malformed, collides with the host's kinds, or drops a kind an
+ * element or link still uses. A host's dialect-specific checks (e.g. goal-controller's own
+ * validation of the block) run as an `ActionGuard` on this operation's kind, so their refusal
+ * also comes back as diagnostics.
+ */
+export interface SetFileMetamodelOperation extends Operation {
+  readonly kind: "istar.setFileMetamodel";
+  readonly block: FileMetamodel | null;
+}
 /** Every operation, keyed by `kind`. */
-export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation;
+export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation;
 export interface RequestModelAction extends RequestAction {
   readonly kind: "requestModel";
   readonly options?: Args;
@@ -477,10 +504,28 @@ export interface ActionDispatcher<EK extends string = ElementKind, LK extends st
  * the operation; others are returned with the result.
  */
 export type ActionGuard<EK extends string = ElementKind, LK extends string = LinkKind> = (operation: IstarOperation<EK, LK>, model: IstarModel<EK, LK>) => readonly GoalDiagnostic[] | void;
+/**
+ * A host's rule, run after each operation is applied (and after each operation of a compound
+ * one, plus once more on the compound's own result), inside the operation's transaction. Sees
+ * the model as the operation leaves it (`modelAfter`) and as it was before (`modelBefore`), so
+ * it can check things a pre-guard can't without re-applying the operation itself (goal-controller's
+ * edgeV2 engine check is the motivating case). Diagnostics of severity `error` roll the
+ * transaction back: the model is untouched and there is no undo entry. Others are returned with
+ * the result, merged with pre-guards' warnings.
+ */
+export type ActionPostGuard<EK extends string = ElementKind, LK extends string = LinkKind> = (operation: IstarOperation<EK, LK>, modelAfter: IstarModel<EK, LK>, modelBefore: IstarModel<EK, LK>) => readonly GoalDiagnostic[] | void;
 export interface ActionDispatcherOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
   readonly guards?: readonly ActionGuard<EK, LK>[];
-  /** What `RequestContextActions` offers. Default: `DEFAULT_PALETTE` (iStar 2.0's). */
-  readonly palette?: AnyPaletteDescription;
+  /** Run after each operation is applied; see `ActionPostGuard`. */
+  readonly postGuards?: readonly ActionPostGuard<EK, LK>[];
+  /**
+   * What `RequestContextActions` offers: a fixed description, or a function evaluated on each
+   * request (so a host can track a registry or extensions that change after this dispatcher was
+   * created — a plain `AnyPaletteDescription` is read once, at creation). Default: derived from
+   * the model's current metamodel (`paletteFromMetamodel`), the same fallback `contributionFor`
+   * (`@istar-ts/glsp`) uses — not iStar 2.0's palette regardless of dialect.
+   */
+  readonly palette?: AnyPaletteDescription | (() => AnyPaletteDescription);
   /**
    * Property schemas an operation must not break: an operation that adds an issue
    * (`validateModelProperties`) is rejected. Their issues are also markers.
@@ -527,6 +572,15 @@ export declare function typeHintsFor<EK extends string, LK extends string>(metam
  * lacks are left out.
  */
 export declare function contextActionsFor<EK extends string, LK extends string>(palette: AnyPaletteDescription, metamodel: Metamodel<EK, LK>): Pick<SetContextActions, "actions" | "groups">;
+/**
+ * A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+ * (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+ * an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+ * hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+ * `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+ * was given.
+ */
+export declare function paletteFromMetamodel(metamodel: AnyMetamodel): AnyPaletteDescription;
 //#endregion
 //#region src/host.d.ts
 /** A host's knowledge for the model: a system-prompt section and/or an MCP resource. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PALETTE, DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties } from "@istar-ts/core";
+import { DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, MetamodelError, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties, withFileMetamodel } from "@istar-ts/core";
 //#region src/actions.ts
 const OPERATION_KIND_LIST = [
 	"createNode",
@@ -16,7 +16,9 @@ const OPERATION_KIND_LIST = [
 	"istar.updateProperties",
 	"istar.updateDisplay",
 	"istar.setLinkValue",
-	"istar.updateLinkDisplay"
+	"istar.updateLinkDisplay",
+	"istar.changeLinkKind",
+	"istar.setFileMetamodel"
 ];
 const REQUEST_KIND_LIST = [
 	"requestModel",
@@ -183,6 +185,36 @@ function contextActionsFor(palette, metamodel) {
 		groups: palette.groups
 	};
 }
+/**
+* A minimal palette for a metamodel with none of its own: one toolbar entry per visible kind
+* (declaration order, actors first), labelled from the kind's own `label`. Kinds generated for
+* an n-ary link (a hub, leg or end — `role` set) are hidden, as a hand-written palette would
+* hide them (`KAOS_PALETTE`'s `RefinementLinkHub: false`, for instance). The fallback
+* `createActionDispatcher` and `contributionFor` (`@istar-ts/glsp`) both use when no palette
+* was given.
+*/
+function paletteFromMetamodel(metamodel) {
+	const elements = {};
+	let order = 0;
+	for (const definition of metamodel.elements.values()) elements[definition.kind] = definition.role !== void 0 ? false : {
+		label: definition.label,
+		order: order++,
+		section: definition.category === "actor" ? "actors" : "elements",
+		...definition.category === "actor" ? { group: "actors" } : {}
+	};
+	const links = {};
+	order = 0;
+	for (const definition of metamodel.links.values()) links[definition.kind] = definition.role !== void 0 ? false : [{
+		label: definition.label,
+		order: order++,
+		section: "elements"
+	}];
+	return {
+		elements,
+		links,
+		groups: { actors: { label: "Actor" } }
+	};
+}
 //#endregion
 //#region src/markers.ts
 /** A `GoalDiagnostic` as a GLSP marker: `kind` is its severity, `label` its message. */
@@ -273,7 +305,12 @@ function linkIssueDiagnostics(model) {
 function createActionDispatcher(store, options = {}) {
 	const s = store;
 	const guards = options.guards ?? [];
-	const palette = options.palette ?? DEFAULT_PALETTE;
+	const postGuards = options.postGuards ?? [];
+	const resolvePalette = (meta) => {
+		const option = options.palette;
+		if (typeof option === "function") return option();
+		return option ?? paletteFromMetamodel(meta);
+	};
 	const sourceModelName = options.sourceModelName ?? "";
 	const listeners = /* @__PURE__ */ new Set();
 	let saved = s.getModel();
@@ -318,8 +355,18 @@ function createActionDispatcher(store, options = {}) {
 		for (const guard of guards) for (const d of guard(operation, s.getModel()) ?? []) (d.severity === "error" ? errors : warnings).push(d);
 		if (errors.length > 0) throw new Rejection(errors);
 	};
+	const runPostGuards = (operation, before, warnings) => {
+		const errors = [];
+		for (const guard of postGuards) for (const d of guard(operation, s.getModel(), before) ?? []) (d.severity === "error" ? errors : warnings).push(d);
+		if (errors.length > 0) throw new Rejection(errors);
+	};
 	const apply = (operation, warnings) => {
 		runGuards(operation, warnings);
+		const before = s.getModel();
+		doApply(operation, warnings);
+		runPostGuards(operation, before, warnings);
+	};
+	const doApply = (operation, warnings) => {
 		const model = s.getModel();
 		const meta = metaOf(model);
 		switch (operation.kind) {
@@ -486,6 +533,45 @@ function createActionDispatcher(store, options = {}) {
 				s.updateLink(linkId, { label: value });
 				return;
 			}
+			case "istar.changeLinkKind": {
+				const { linkIds, elementTypeId: kind } = operation;
+				if (linkIds.length === 0) return;
+				const ids = new Set(linkIds);
+				const links = [...ids].map((id) => model.links.get(id) ?? reject(`unknown link "${id}"`, id, "unknown-element"));
+				const definition = meta.links.get(kind) ?? reject(`unknown link kind "${kind}" in ${meta.name}`, "", "unknown-kind");
+				const toChange = links.filter((link) => link.kind !== kind);
+				if (toChange.length === 0) return;
+				const remaining = new Map(model.links);
+				for (const id of ids) remaining.delete(id);
+				const without = withLinks(model, remaining);
+				const values = definition.info.possibleLabels;
+				for (const link of toChange) {
+					const check = canLink(without, link.source, link.target, kind);
+					if (!check.ok) rejectCheck(check, {
+						source: link.source,
+						target: link.target
+					});
+					if (link.label != null && values && !values.includes(link.label)) reject(`"${link.label}" is not a value of a ${definition.label} link (${values.join(", ")})`, link.id, "invalid-value");
+				}
+				const next = new Map(model.links);
+				for (const link of toChange) next.set(link.id, {
+					...link,
+					kind
+				});
+				s.replace(withLinks(model, next));
+				return;
+			}
+			case "istar.setFileMetamodel": {
+				let next;
+				try {
+					next = withFileMetamodel(model, operation.block);
+				} catch (error) {
+					if (error instanceof MetamodelError) reject(error.message, "", "invalid-metamodel");
+					throw error;
+				}
+				s.replace(next);
+				return;
+			}
 			default: reject(`unknown operation "${operation.kind}"`, "", "unknown-action");
 		}
 	};
@@ -646,11 +732,14 @@ function createActionDispatcher(store, options = {}) {
 				...typeHintsFor(metaOf(model))
 			};
 			case "requestCheckEdge": return checkEdge(action);
-			case "requestContextActions": return {
-				kind: "setContextActions",
-				responseId: action.requestId,
-				...contextActionsFor(palette, metaOf(model))
-			};
+			case "requestContextActions": {
+				const meta = metaOf(model);
+				return {
+					kind: "setContextActions",
+					responseId: action.requestId,
+					...contextActionsFor(resolvePalette(meta), meta)
+				};
+			}
 			case "requestMarkers": return markers(action);
 			default: return;
 		}
@@ -1098,6 +1187,6 @@ function createRemoteDispatcher(port) {
 /** Version of the action protocol this package speaks. */
 const ACTIONS_PROTOCOL_VERSION = "0.0.0";
 //#endregion
-export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, isOperation, isRequestAction, markerToDiagnostic, readOnlyDispatcher, typeHintsFor };
+export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, isOperation, isRequestAction, markerToDiagnostic, paletteFromMetamodel, readOnlyDispatcher, typeHintsFor };
 
 //# sourceMappingURL=index.js.map