@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/commands/update.js

@@ -1,15 +1,23 @@
 import ansis from "ansis";
 import { Model } from "../core/model.js";
 import { MutationHandler } from "../core/mutation-handler.js";
+import { setStagedSourceReference } from "../core/staged-source-reference.js";
 import { StagingAreaManager } from "../core/staging-area.js";
 import { StagedChangesetStorage } from "../core/staged-changeset-storage.js";
+import { changedFields as snapshotChangedFields } from "../core/changeset-summary.js";
 import { findElementLayer } from "../utils/element-utils.js";
-import { CLIError, handleError, handleSuccess, handleInfo, findSimilar, formatValidOptions } from "../utils/errors.js";
+import { CLIError, handleError, handleSuccess, handleInfo, handleWarning, findSimilar, formatValidOptions } from "../utils/errors.js";
 import { isValidNodeType, getNodeTypesForLayer, normalizeNodeType } from "../generated/node-types.js";
 import { Element } from "../core/element.js";
 import { Layer } from "../core/layer.js";
-import { SchemaValidator } from "../validators/schema-validator.js";
+import { SchemaValidator, suggestNodeTypes } from "../validators/schema-validator.js";
 import { validateSourceReferenceOptions, buildSourceReference } from "../utils/source-reference.js";
+import { schemaLookupHint, undefinedTypeWarning } from "../utils/error-hints.js";
+import { effectiveAttributePatch, parseJsonObjectOption, resolveAttributeUpdate } from "../utils/attribute-patch.js";
+function undefinedTypeCheck(layer, elementId, type) {
+  if (!isValidNodeType(layer, type))
+    return undefinedTypeWarning("cli", layer, elementId, type, suggestNodeTypes(layer, type));
+}
 import { startSpan, endSpan } from "../telemetry/index.js";
 const isTelemetryEnabled = !1;
 function validateUpdateSourceReferenceOptions(options) {
@@ -20,14 +28,16 @@ function validateUpdateSourceReferenceOptions(options) {
 }
 async function updateCommand(id, options) {
   const changedFields = [];
-  options.name && changedFields.push("name"), options.description && changedFields.push("description"), options.type && changedFields.push("type"), options.attributes && changedFields.push("attributes"), (options.sourceFile || options.clearSourceReference) && changedFields.push("sourceReference");
+  options.name && changedFields.push("name"), options.description && changedFields.push("description"), options.type && changedFields.push("type"), (options.attributes || options.attributePatch) && changedFields.push("attributes"), (options.sourceFile || options.clearSourceReference) && changedFields.push("sourceReference");
   const span = isTelemetryEnabled ? startSpan("element.update", {
     "element.id": id,
     "element.changed_fields": changedFields.join(",")
   }) : null;
   try {
     validateUpdateSourceReferenceOptions(options);
-    const model = await Model.load(options.model || process.cwd()), layerName = await findElementLayer(model, id);
+    const parsedPatch = options.attributePatch !== void 0 ? parseJsonObjectOption(options.attributePatch, "--attribute-patch") : void 0, attributeFlags = { attributes: "--attributes", attributePatch: "--attribute-patch" };
+    options.attributes !== void 0 && parsedPatch !== void 0 && resolveAttributeUpdate(void 0, { attributes: {}, attributePatch: parsedPatch }, attributeFlags);
+    const attributePatch = effectiveAttributePatch(parsedPatch), model = await Model.load(options.model), layerName = await findElementLayer(model, id);
     if (!layerName) {
       const stagingManager = new StagingAreaManager(model.rootPath, model), storage = new StagedChangesetStorage(model.rootPath), activeId = await stagingManager.getActiveId();
       if (activeId) {
@@ -35,7 +45,7 @@ async function updateCommand(id, options) {
         if (changeset) {
           const addChange = changeset.changes.find((c) => c.type === "add" && c.elementId === id);
           if (addChange && addChange.after) {
-            if (!(options.name || options.description !== void 0 || options.attributes || options.sourceFile || options.clearSourceReference || options.type)) {
+            if (!(options.name || options.description !== void 0 || options.attributes || attributePatch || options.sourceFile || options.clearSourceReference || options.type)) {
               handleInfo(ansis.yellow("No fields specified for update"));
               return;
             }
@@ -58,13 +68,14 @@ async function updateCommand(id, options) {
                   "Ensure your JSON is valid and properly formatted"
                 ]);
               }
+            else attributePatch && (after.attributes = resolveAttributeUpdate(after.attributes, { attributePatch }, attributeFlags));
             if (options.clearSourceReference)
-              delete after.source_reference;
+              setStagedSourceReference(after, void 0);
             else if (options.sourceFile) {
               const newRef = buildSourceReference(options);
-              newRef && (after.source_reference = newRef);
+              newRef && setStagedSourceReference(after, newRef);
             }
-            if (options.type || options.attributes) {
+            if (options.type || options.attributes || attributePatch) {
               const stagedLayerName = addChange.layerName, tempElem = Element.fromSpecNode({
                 id: String(after.id ?? addChange.elementId ?? "staged"),
                 path: String(after.path ?? addChange.elementId ?? ""),
@@ -75,15 +86,16 @@ async function updateCommand(id, options) {
                 attributes: after.attributes || {}
               }), schemaValidator = new SchemaValidator(), tempLayer = new Layer(stagedLayerName);
               tempLayer.addElement(tempElem);
-              const attrValidation = await schemaValidator.validateLayer(tempLayer);
-              if (!attrValidation.isValid()) {
-                const errorMessages = attrValidation.errors.map((e) => `  ${e.message}`).join(`
+              const attrValidation = await schemaValidator.validateLayer(tempLayer), undefinedTypeHint = undefinedTypeCheck(stagedLayerName, id, String(after.type ?? "")), blocking = undefinedTypeHint ? attrValidation.errors.filter((e) => e.location !== "/type") : attrValidation.errors;
+              if (blocking.length > 0) {
+                const errorMessages = blocking.map((e) => `  ${e.message}`).join(`
 `);
                 throw new CLIError(`Updated attributes fail schema validation:
 ${errorMessages}`, 1, [
-                  options.type ? `Incompatible attributes must be manually cleaned up before changing type. Run "dr schema ${stagedLayerName} ${after.type}" to see the required attributes` : `Run "dr schema ${stagedLayerName} ${after.type}" to see the required attributes`
+                  undefinedTypeHint ? undefinedTypeHint.hint : (options.type ? "Incompatible attributes must be manually cleaned up before changing type. " : "") + schemaLookupHint("cli", stagedLayerName, String(after.type))
                 ]);
               }
+              undefinedTypeHint && handleWarning(undefinedTypeHint.message, [undefinedTypeHint.hint]);
             }
             await storage.updateChange(activeId, id, {
               type: addChange.type,
@@ -94,7 +106,8 @@ ${errorMessages}`, 1, [
             }), handleSuccess(`Updated staged element ${ansis.bold(id)}`, {
               elementId: id,
               layer: addChange.layerName,
-              changesetStatus: "staged"
+              changesetStatus: "staged",
+              changedFields: snapshotChangedFields(addChange.after, after)
             }, { verbose: options.verbose });
             return;
           }
@@ -108,11 +121,12 @@ ${errorMessages}`, 1, [
     const element = layer.getElement(id);
     if (!element)
       throw new CLIError(`Element ${id} not found`, 1);
-    if (!(options.name || options.description !== void 0 || options.type || options.attributes || options.sourceFile || options.clearSourceReference)) {
+    if (!(options.name || options.description !== void 0 || options.type || options.attributes || attributePatch || options.sourceFile || options.clearSourceReference)) {
       handleInfo(ansis.yellow("No fields specified for update"));
       return;
     }
-    await new MutationHandler(model, id, layerName).executeUpdate(element, async (elem, after) => {
+    const handler = new MutationHandler(model, id, layerName);
+    await handler.executeUpdate(element, async (elem, after) => {
       let resolvedNewType;
       if (options.type) {
         if (!isValidNodeType(layerName, options.type)) {
@@ -130,6 +144,7 @@ ${errorMessages}`, 1, [
             "Ensure your JSON is valid and properly formatted"
           ]);
         }
+      else attributePatch && (parsedAttributes = resolveAttributeUpdate(elem.attributes, { attributePatch }, attributeFlags));
       if (resolvedNewType || parsedAttributes) {
         const candidateType = resolvedNewType ?? elem.type, tempElem = new Element({
           ...elem.toJSON(),
@@ -138,21 +153,22 @@ ${errorMessages}`, 1, [
           attributes: parsedAttributes ?? elem.attributes
         }), schemaValidator = new SchemaValidator(), tempLayer = new Layer(layerName);
         tempLayer.addElement(tempElem);
-        const attrValidation = await schemaValidator.validateLayer(tempLayer);
-        if (!attrValidation.isValid()) {
-          const errorMessages = attrValidation.errors.map((e) => `  ${e.message}`).join(`
+        const attrValidation = await schemaValidator.validateLayer(tempLayer), undefinedTypeHint = undefinedTypeCheck(layerName, id, candidateType), blocking = undefinedTypeHint ? attrValidation.errors.filter((e) => e.location !== "/type") : attrValidation.errors;
+        if (blocking.length > 0) {
+          const errorMessages = blocking.map((e) => `  ${e.message}`).join(`
 `);
           throw new CLIError(`Updated attributes fail schema validation:
 ${errorMessages}`, 1, [
-            resolvedNewType ? `Incompatible attributes must be manually cleaned up before changing type. Run "dr schema ${layerName} ${candidateType}" to see the required attributes` : `Run "dr schema ${layerName} ${elem.type}" to see the required attributes`
+            undefinedTypeHint ? undefinedTypeHint.hint : resolvedNewType ? "Incompatible attributes must be manually cleaned up before changing type. " + schemaLookupHint("cli", layerName, candidateType) : schemaLookupHint("cli", layerName, elem.type)
           ]);
         }
+        undefinedTypeHint && handleWarning(undefinedTypeHint.message, [undefinedTypeHint.hint]);
       }
       if (resolvedNewType && (elem.type = resolvedNewType, after.type = resolvedNewType, elem.spec_node_id = `${layerName}.${resolvedNewType}`, after.spec_node_id = `${layerName}.${resolvedNewType}`), options.name && (elem.name = options.name, after.name = options.name), options.description !== void 0 && (elem.description = options.description || void 0, after.description = options.description || void 0), parsedAttributes && (elem.attributes = parsedAttributes, after.attributes = parsedAttributes), options.clearSourceReference)
-        elem.setSourceReference(void 0), after.sourceReference = void 0;
+        elem.setSourceReference(void 0), setStagedSourceReference(after, void 0);
       else if (options.sourceFile) {
         const newRef = buildSourceReference(options);
-        newRef && (elem.setSourceReference(newRef), after.sourceReference = newRef);
+        newRef && (elem.setSourceReference(newRef), setStagedSourceReference(after, newRef));
       }
       layer.updateElement(elem);
     });
@@ -162,9 +178,12 @@ ${errorMessages}`, 1, [
       elementId: id,
       layer: layerName,
       name: element.name,
-      changes
+      changes,
+      changedFields: handler.getChangedFields(),
+      // The active changeset adds this element: the update was folded into that add.
+      ...handler.wasFoldedIntoAdd() ? { foldedIntoAdd: !0 } : {}
     };
-    handleSuccess(`Updated element ${ansis.bold(id)}`, details, { verbose: options.verbose });
+    handleSuccess(`Updated ${handler.wasFoldedIntoAdd() ? "staged " : ""}element ${ansis.bold(id)}` + (handler.getChangedFields().length > 0 ? ` (${handler.getChangedFields().join(", ")})` : ""), details, { verbose: options.verbose });
   } catch (error) {
     isTelemetryEnabled && span && (span.recordException(error), span.setStatus({ code: 2, message: error.message })), handleError(error);
   } finally {

package/dist/commands/update.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/commands/update.ts"],
-  "sourcesContent": ["/**\n * Update an element\n */\n\nimport ansis from \"ansis\";\nimport { Model } from \"../core/model.js\";\nimport { MutationHandler } from \"../core/mutation-handler.js\";\nimport { StagingAreaManager } from \"../core/staging-area.js\";\nimport { StagedChangesetStorage } from \"../core/staged-changeset-storage.js\";\nimport { findElementLayer } from \"../utils/element-utils.js\";\nimport { CLIError, handleError, handleSuccess, handleInfo, findSimilar, formatValidOptions } from \"../utils/errors.js\";\nimport { isValidNodeType, getNodeTypesForLayer, normalizeNodeType } from \"../generated/node-types.js\";\nimport { Element } from \"../core/element.js\";\nimport { Layer } from \"../core/layer.js\";\nimport { SchemaValidator } from \"../validators/schema-validator.js\";\nimport { validateSourceReferenceOptions, buildSourceReference } from \"../utils/source-reference.js\";\nimport { startSpan, endSpan } from \"../telemetry/index.js\";\n\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\nexport interface UpdateOptions {\n  model?: string;\n  name?: string;\n  description?: string;\n  type?: string;\n  attributes?: string;\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n  clearSourceReference?: boolean;\n  verbose?: boolean;\n  debug?: boolean;\n}\n\n/**\n * Validate update-specific source reference options\n */\nfunction validateUpdateSourceReferenceOptions(options: UpdateOptions): void {\n  const hasSourceOptions =\n    options.sourceFile ||\n    options.sourceSymbol ||\n    options.sourceProvenance ||\n    options.sourceRepoRemote ||\n    options.sourceRepoCommit;\n\n  if (options.clearSourceReference && hasSourceOptions) {\n    throw new CLIError(\n      \"Cannot use --clear-source-reference with other source reference options\",\n      1,\n      [\"Specify either --clear-source-reference or other source options, not both\"]\n    );\n  }\n\n  // Use shared validation for source reference options if any are provided\n  if (hasSourceOptions) {\n    validateSourceReferenceOptions(options);\n  }\n}\n\nexport async function updateCommand(id: string, options: UpdateOptions): Promise<void> {\n  const changedFields: string[] = [];\n  if (options.name) changedFields.push(\"name\");\n  if (options.description) changedFields.push(\"description\");\n  if (options.type) changedFields.push(\"type\");\n  if (options.attributes) changedFields.push(\"attributes\");\n  if (options.sourceFile || options.clearSourceReference) changedFields.push(\"sourceReference\");\n\n  const span = isTelemetryEnabled\n    ? startSpan(\"element.update\", {\n        \"element.id\": id,\n        \"element.changed_fields\": changedFields.join(\",\"),\n      })\n    : null;\n\n  try {\n    // Validate source reference options\n    validateUpdateSourceReferenceOptions(options);\n\n    // Load model\n    const model = await Model.load(options.model || process.cwd());\n\n    // Find element\n    const layerName = await findElementLayer(model, id);\n    if (!layerName) {\n      // Not in committed model \u2014 check active changeset for a staged ADD\n      const stagingManager = new StagingAreaManager(model.rootPath, model);\n      const storage = new StagedChangesetStorage(model.rootPath);\n      const activeId = await stagingManager.getActiveId();\n\n      if (activeId) {\n        const changeset = await storage.load(activeId);\n        if (changeset) {\n          const addChange = changeset.changes.find(\n            (c) => c.type === \"add\" && c.elementId === id\n          );\n          if (addChange && addChange.after) {\n            const hasUpdates =\n              options.name ||\n              options.description !== undefined ||\n              options.attributes ||\n              options.sourceFile ||\n              options.clearSourceReference ||\n              options.type;\n\n            if (!hasUpdates) {\n              handleInfo(ansis.yellow(\"No fields specified for update\"));\n              return;\n            }\n\n            const after: Record<string, unknown> = { ...addChange.after };\n\n            if (options.type) {\n              const stagedLayerName = addChange.layerName;\n              if (!isValidNodeType(stagedLayerName, options.type)) {\n                const validNodeTypes = getNodeTypesForLayer(stagedLayerName);\n                const typeNames = validNodeTypes.map((t) => t.type).sort();\n                const similar = findSimilar(options.type, typeNames, 3);\n                const suggestions: string[] = [`Valid types for ${stagedLayerName}: ${formatValidOptions(typeNames)}`];\n                if (similar.length > 0) suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n                throw new CLIError(`Invalid element type \"${options.type}\" for layer \"${stagedLayerName}\"`, 1, suggestions);\n              }\n              const resolvedNewType = normalizeNodeType(stagedLayerName, options.type);\n              after.type = resolvedNewType;\n              after.spec_node_id = `${stagedLayerName}.${resolvedNewType}`;\n            }\n            if (options.name) after.name = options.name;\n            if (options.description !== undefined) {\n              after.description = options.description || undefined;\n            }\n            if (options.attributes) {\n              try {\n                const parsed = JSON.parse(options.attributes);\n                after.attributes = parsed;\n              } catch {\n                throw new CLIError(\"Invalid JSON in --attributes\", 1, [\n                  \"Ensure your JSON is valid and properly formatted\",\n                ]);\n              }\n            }\n            if (options.clearSourceReference) {\n              delete after.source_reference;\n            } else if (options.sourceFile) {\n              const newRef = buildSourceReference(options);\n              if (newRef) after.source_reference = newRef;\n            }\n\n            // Validate schema if type or attributes changed in staged element\n            if (options.type || options.attributes) {\n              const stagedLayerName = addChange.layerName;\n              const tempElem = Element.fromSpecNode({\n                id: String(after.id ?? addChange.elementId ?? \"staged\"),\n                path: String(after.path ?? addChange.elementId ?? \"\"),\n                spec_node_id: String(after.spec_node_id ?? \"\"),\n                type: String(after.type ?? \"\"),\n                layer_id: String(after.layer_id ?? stagedLayerName),\n                name: String(after.name ?? \"\"),\n                attributes: (after.attributes as Record<string, unknown>) || {},\n              });\n              const schemaValidator = new SchemaValidator();\n              const tempLayer = new Layer(stagedLayerName);\n              tempLayer.addElement(tempElem);\n              const attrValidation = await schemaValidator.validateLayer(tempLayer);\n              if (!attrValidation.isValid()) {\n                const errorMessages = attrValidation.errors\n                  .map((e) => `  ${e.message}`)\n                  .join(\"\\n\");\n                throw new CLIError(\n                  `Updated attributes fail schema validation:\\n${errorMessages}`,\n                  1,\n                  [\n                    options.type\n                      ? `Incompatible attributes must be manually cleaned up before changing type. Run \"dr schema ${stagedLayerName} ${after.type}\" to see the required attributes`\n                      : `Run \"dr schema ${stagedLayerName} ${after.type}\" to see the required attributes`,\n                  ]\n                );\n              }\n            }\n\n            await storage.updateChange(activeId, id, {\n              type: addChange.type,\n              elementId: addChange.elementId,\n              layerName: addChange.layerName,\n              before: addChange.before,\n              after,\n            });\n\n            handleSuccess(`Updated staged element ${ansis.bold(id)}`, {\n              elementId: id,\n              layer: addChange.layerName,\n              changesetStatus: \"staged\",\n            }, { verbose: options.verbose });\n            return;\n          }\n        }\n      }\n\n      throw new CLIError(`Element ${id} not found`, 1);\n    }\n\n    const layer = await model.getLayer(layerName);\n    if (!layer) {\n      throw new CLIError(`Layer ${layerName} not found`, 1);\n    }\n\n    const element = layer.getElement(id);\n    if (!element) {\n      throw new CLIError(`Element ${id} not found`, 1);\n    }\n\n    // Validate that at least one field is specified\n    const hasUpdates =\n      options.name ||\n      options.description !== undefined ||\n      options.type ||\n      options.attributes ||\n      options.sourceFile ||\n      options.clearSourceReference;\n\n    if (!hasUpdates) {\n      handleInfo(ansis.yellow(\"No fields specified for update\"));\n      return;\n    }\n\n    // Single unified mutation handler for update\n    const handler = new MutationHandler(model, id, layerName);\n\n    // Execute update through unified path (handles staging and base model consistently)\n    // The mutator function applies all updates in a single pass with validated JSON parsing\n    await handler.executeUpdate(element, async (elem, after) => {\n      // Resolve new type (validate name only \u2014 don't mutate live elem yet)\n      let resolvedNewType: string | undefined;\n      if (options.type) {\n        if (!isValidNodeType(layerName, options.type)) {\n          const validNodeTypes = getNodeTypesForLayer(layerName);\n          const typeNames = validNodeTypes.map((t) => t.type).sort();\n          const similar = findSimilar(options.type, typeNames, 3);\n          const suggestions: string[] = [`Valid types for ${layerName}: ${formatValidOptions(typeNames)}`];\n          if (similar.length > 0) suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n          throw new CLIError(`Invalid element type \"${options.type}\" for layer \"${layerName}\"`, 1, suggestions);\n        }\n        resolvedNewType = normalizeNodeType(layerName, options.type);\n      }\n\n      // Parse attributes (don't mutate yet)\n      let parsedAttributes: Record<string, unknown> | undefined;\n      if (options.attributes) {\n        try {\n          parsedAttributes = JSON.parse(options.attributes) as Record<string, unknown>;\n        } catch (e) {\n          throw new CLIError(\"Invalid JSON in --attributes\", 1, [\n            \"Ensure your JSON is valid and properly formatted\",\n          ]);\n        }\n      }\n\n      // Validate against schema using a temp element BEFORE mutating the live elem\n      if (resolvedNewType || parsedAttributes) {\n        const candidateType = resolvedNewType ?? elem.type;\n        const tempElem = new Element({\n          ...elem.toJSON(),\n          type: candidateType,\n          spec_node_id: `${layerName}.${candidateType}`,\n          attributes: parsedAttributes ?? elem.attributes,\n        });\n        const schemaValidator = new SchemaValidator();\n        const tempLayer = new Layer(layerName);\n        tempLayer.addElement(tempElem);\n        const attrValidation = await schemaValidator.validateLayer(tempLayer);\n        if (!attrValidation.isValid()) {\n          const errorMessages = attrValidation.errors\n            .map((e) => `  ${e.message}`)\n            .join(\"\\n\");\n          throw new CLIError(\n            `Updated attributes fail schema validation:\\n${errorMessages}`,\n            1,\n            [\n              resolvedNewType\n                ? `Incompatible attributes must be manually cleaned up before changing type. Run \"dr schema ${layerName} ${candidateType}\" to see the required attributes`\n                : `Run \"dr schema ${layerName} ${elem.type}\" to see the required attributes`,\n            ]\n          );\n        }\n      }\n\n      // Validation passed \u2014 apply all mutations to live element\n      if (resolvedNewType) {\n        elem.type = resolvedNewType;\n        after.type = resolvedNewType;\n        elem.spec_node_id = `${layerName}.${resolvedNewType}`;\n        after.spec_node_id = `${layerName}.${resolvedNewType}`;\n      }\n\n      if (options.name) {\n        elem.name = options.name;\n        after.name = options.name;\n      }\n\n      if (options.description !== undefined) {\n        elem.description = options.description || undefined;\n        after.description = options.description || undefined;\n      }\n\n      if (parsedAttributes) {\n        elem.attributes = parsedAttributes;\n        after.attributes = parsedAttributes;\n      }\n\n      if (options.clearSourceReference) {\n        elem.setSourceReference(undefined);\n        after.sourceReference = undefined;\n      } else if (options.sourceFile) {\n        const newRef = buildSourceReference(options);\n        if (newRef) {\n          elem.setSourceReference(newRef);\n          after.sourceReference = newRef;\n        }\n      }\n\n      // Update element in layer graph to persist mutations\n      layer.updateElement(elem);\n    });\n\n    const changes: Record<string, unknown> = {};\n    if (options.type) changes.type = options.type;\n    if (options.name) changes.name = options.name;\n    if (options.description !== undefined) changes.description = options.description;\n    if (options.sourceFile) changes.source = options.sourceFile;\n    if (options.clearSourceReference) changes.source = \"cleared\";\n\n    const details: Record<string, unknown> = {\n      elementId: id,\n      layer: layerName,\n      name: element.name,\n      changes,\n    };\n\n    handleSuccess(`Updated element ${ansis.bold(id)}`, details, { verbose: options.verbose });\n  } catch (error) {\n    if (isTelemetryEnabled && span) {\n      (span as any).recordException(error as Error);\n      (span as any).setStatus({ code: 2, message: (error as Error).message });\n    }\n    handleError(error);\n  } finally {\n    if (isTelemetryEnabled) {\n      endSpan(span);\n    }\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Update an element\n */\n\nimport ansis from \"ansis\";\nimport { Model } from \"../core/model.js\";\nimport { MutationHandler } from \"../core/mutation-handler.js\";\nimport { setStagedSourceReference } from \"../core/staged-source-reference.js\";\nimport { StagingAreaManager } from \"../core/staging-area.js\";\nimport { StagedChangesetStorage } from \"../core/staged-changeset-storage.js\";\nimport { changedFields as snapshotChangedFields } from \"../core/changeset-summary.js\";\nimport { findElementLayer } from \"../utils/element-utils.js\";\nimport { CLIError, handleError, handleSuccess, handleInfo, handleWarning, findSimilar, formatValidOptions } from \"../utils/errors.js\";\nimport { isValidNodeType, getNodeTypesForLayer, normalizeNodeType } from \"../generated/node-types.js\";\nimport { Element } from \"../core/element.js\";\nimport { Layer } from \"../core/layer.js\";\nimport { SchemaValidator, suggestNodeTypes } from \"../validators/schema-validator.js\";\nimport { validateSourceReferenceOptions, buildSourceReference } from \"../utils/source-reference.js\";\nimport { schemaLookupHint, undefinedTypeWarning } from \"../utils/error-hints.js\";\nimport { effectiveAttributePatch, parseJsonObjectOption, resolveAttributeUpdate } from \"../utils/attribute-patch.js\";\n\n/**\n * When the element's type (after any requested type change) is one the spec does not define, the\n * warning and type-change hint to give instead of refusing the update; undefined when the type is\n * valid.\n */\nfunction undefinedTypeCheck(\n  layer: string,\n  elementId: string,\n  type: string\n): { message: string; hint: string } | undefined {\n  if (isValidNodeType(layer, type)) return undefined;\n  return undefinedTypeWarning(\"cli\", layer, elementId, type, suggestNodeTypes(layer, type));\n}\nimport { startSpan, endSpan } from \"../telemetry/index.js\";\n\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\nexport interface UpdateOptions {\n  model?: string;\n  name?: string;\n  description?: string;\n  type?: string;\n  attributes?: string;\n  /** JSON object merged into the element's current attributes; a null value removes a key. */\n  attributePatch?: string;\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n  clearSourceReference?: boolean;\n  verbose?: boolean;\n  debug?: boolean;\n}\n\n/**\n * Validate update-specific source reference options\n */\nfunction validateUpdateSourceReferenceOptions(options: UpdateOptions): void {\n  const hasSourceOptions =\n    options.sourceFile ||\n    options.sourceSymbol ||\n    options.sourceProvenance ||\n    options.sourceRepoRemote ||\n    options.sourceRepoCommit;\n\n  if (options.clearSourceReference && hasSourceOptions) {\n    throw new CLIError(\n      \"Cannot use --clear-source-reference with other source reference options\",\n      1,\n      [\"Specify either --clear-source-reference or other source options, not both\"]\n    );\n  }\n\n  // Use shared validation for source reference options if any are provided\n  if (hasSourceOptions) {\n    validateSourceReferenceOptions(options);\n  }\n}\n\nexport async function updateCommand(id: string, options: UpdateOptions): Promise<void> {\n  const changedFields: string[] = [];\n  if (options.name) changedFields.push(\"name\");\n  if (options.description) changedFields.push(\"description\");\n  if (options.type) changedFields.push(\"type\");\n  if (options.attributes || options.attributePatch) changedFields.push(\"attributes\");\n  if (options.sourceFile || options.clearSourceReference) changedFields.push(\"sourceReference\");\n\n  const span = isTelemetryEnabled\n    ? startSpan(\"element.update\", {\n        \"element.id\": id,\n        \"element.changed_fields\": changedFields.join(\",\"),\n      })\n    : null;\n\n  try {\n    // Validate source reference options\n    validateUpdateSourceReferenceOptions(options);\n\n    // --attribute-patch must be a JSON object, and cannot be combined with --attributes.\n    const parsedPatch =\n      options.attributePatch !== undefined ? parseJsonObjectOption(options.attributePatch, \"--attribute-patch\") : undefined;\n    const attributeFlags = { attributes: \"--attributes\", attributePatch: \"--attribute-patch\" };\n    if (options.attributes !== undefined && parsedPatch !== undefined) {\n      resolveAttributeUpdate(undefined, { attributes: {}, attributePatch: parsedPatch }, attributeFlags);\n    }\n    // An empty patch names no key: it is not an update.\n    const attributePatch = effectiveAttributePatch(parsedPatch);\n\n    // Load model\n    const model = await Model.load(options.model);\n\n    // Find element\n    const layerName = await findElementLayer(model, id);\n    if (!layerName) {\n      // Not in committed model \u2014 check active changeset for a staged ADD\n      const stagingManager = new StagingAreaManager(model.rootPath, model);\n      const storage = new StagedChangesetStorage(model.rootPath);\n      const activeId = await stagingManager.getActiveId();\n\n      if (activeId) {\n        const changeset = await storage.load(activeId);\n        if (changeset) {\n          const addChange = changeset.changes.find(\n            (c) => c.type === \"add\" && c.elementId === id\n          );\n          if (addChange && addChange.after) {\n            const hasUpdates =\n              options.name ||\n              options.description !== undefined ||\n              options.attributes ||\n              attributePatch ||\n              options.sourceFile ||\n              options.clearSourceReference ||\n              options.type;\n\n            if (!hasUpdates) {\n              handleInfo(ansis.yellow(\"No fields specified for update\"));\n              return;\n            }\n\n            const after: Record<string, unknown> = { ...addChange.after };\n\n            if (options.type) {\n              const stagedLayerName = addChange.layerName;\n              if (!isValidNodeType(stagedLayerName, options.type)) {\n                const validNodeTypes = getNodeTypesForLayer(stagedLayerName);\n                const typeNames = validNodeTypes.map((t) => t.type).sort();\n                const similar = findSimilar(options.type, typeNames, 3);\n                const suggestions: string[] = [`Valid types for ${stagedLayerName}: ${formatValidOptions(typeNames)}`];\n                if (similar.length > 0) suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n                throw new CLIError(`Invalid element type \"${options.type}\" for layer \"${stagedLayerName}\"`, 1, suggestions);\n              }\n              const resolvedNewType = normalizeNodeType(stagedLayerName, options.type);\n              after.type = resolvedNewType;\n              after.spec_node_id = `${stagedLayerName}.${resolvedNewType}`;\n            }\n            if (options.name) after.name = options.name;\n            if (options.description !== undefined) {\n              after.description = options.description || undefined;\n            }\n            if (options.attributes) {\n              try {\n                const parsed = JSON.parse(options.attributes);\n                after.attributes = parsed;\n              } catch {\n                throw new CLIError(\"Invalid JSON in --attributes\", 1, [\n                  \"Ensure your JSON is valid and properly formatted\",\n                ]);\n              }\n            } else if (attributePatch) {\n              after.attributes = resolveAttributeUpdate(\n                after.attributes as Record<string, unknown> | undefined,\n                { attributePatch },\n                attributeFlags\n              );\n            }\n            if (options.clearSourceReference) {\n              setStagedSourceReference(after, undefined);\n            } else if (options.sourceFile) {\n              const newRef = buildSourceReference(options);\n              if (newRef) setStagedSourceReference(after, newRef);\n            }\n\n            // Validate schema if type or attributes changed in staged element\n            if (options.type || options.attributes || attributePatch) {\n              const stagedLayerName = addChange.layerName;\n              const tempElem = Element.fromSpecNode({\n                id: String(after.id ?? addChange.elementId ?? \"staged\"),\n                path: String(after.path ?? addChange.elementId ?? \"\"),\n                spec_node_id: String(after.spec_node_id ?? \"\"),\n                type: String(after.type ?? \"\"),\n                layer_id: String(after.layer_id ?? stagedLayerName),\n                name: String(after.name ?? \"\"),\n                attributes: (after.attributes as Record<string, unknown>) || {},\n              });\n              const schemaValidator = new SchemaValidator();\n              const tempLayer = new Layer(stagedLayerName);\n              tempLayer.addElement(tempElem);\n              const attrValidation = await schemaValidator.validateLayer(tempLayer);\n              const undefinedTypeHint = undefinedTypeCheck(stagedLayerName, id, String(after.type ?? \"\"));\n              const blocking = undefinedTypeHint\n                ? attrValidation.errors.filter((e) => e.location !== \"/type\")\n                : attrValidation.errors;\n              if (blocking.length > 0) {\n                const errorMessages = blocking\n                  .map((e) => `  ${e.message}`)\n                  .join(\"\\n\");\n                throw new CLIError(\n                  `Updated attributes fail schema validation:\\n${errorMessages}`,\n                  1,\n                  [\n                    undefinedTypeHint\n                      ? undefinedTypeHint.hint\n                      : (options.type\n                          ? \"Incompatible attributes must be manually cleaned up before changing type. \"\n                          : \"\") + schemaLookupHint(\"cli\", stagedLayerName, String(after.type)),\n                  ]\n                );\n              }\n              if (undefinedTypeHint) handleWarning(undefinedTypeHint.message, [undefinedTypeHint.hint]);\n            }\n\n            await storage.updateChange(activeId, id, {\n              type: addChange.type,\n              elementId: addChange.elementId,\n              layerName: addChange.layerName,\n              before: addChange.before,\n              after,\n            });\n\n            handleSuccess(`Updated staged element ${ansis.bold(id)}`, {\n              elementId: id,\n              layer: addChange.layerName,\n              changesetStatus: \"staged\",\n              changedFields: snapshotChangedFields(addChange.after, after),\n            }, { verbose: options.verbose });\n            return;\n          }\n        }\n      }\n\n      throw new CLIError(`Element ${id} not found`, 1);\n    }\n\n    const layer = await model.getLayer(layerName);\n    if (!layer) {\n      throw new CLIError(`Layer ${layerName} not found`, 1);\n    }\n\n    const element = layer.getElement(id);\n    if (!element) {\n      throw new CLIError(`Element ${id} not found`, 1);\n    }\n\n    // Validate that at least one field is specified\n    const hasUpdates =\n      options.name ||\n      options.description !== undefined ||\n      options.type ||\n      options.attributes ||\n      attributePatch ||\n      options.sourceFile ||\n      options.clearSourceReference;\n\n    if (!hasUpdates) {\n      handleInfo(ansis.yellow(\"No fields specified for update\"));\n      return;\n    }\n\n    // Single unified mutation handler for update\n    const handler = new MutationHandler(model, id, layerName);\n\n    // Execute update through unified path (handles staging and base model consistently)\n    // The mutator function applies all updates in a single pass with validated JSON parsing\n    await handler.executeUpdate(element, async (elem, after) => {\n      // Resolve new type (validate name only \u2014 don't mutate live elem yet)\n      let resolvedNewType: string | undefined;\n      if (options.type) {\n        if (!isValidNodeType(layerName, options.type)) {\n          const validNodeTypes = getNodeTypesForLayer(layerName);\n          const typeNames = validNodeTypes.map((t) => t.type).sort();\n          const similar = findSimilar(options.type, typeNames, 3);\n          const suggestions: string[] = [`Valid types for ${layerName}: ${formatValidOptions(typeNames)}`];\n          if (similar.length > 0) suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n          throw new CLIError(`Invalid element type \"${options.type}\" for layer \"${layerName}\"`, 1, suggestions);\n        }\n        resolvedNewType = normalizeNodeType(layerName, options.type);\n      }\n\n      // Parse attributes (don't mutate yet)\n      let parsedAttributes: Record<string, unknown> | undefined;\n      if (options.attributes) {\n        try {\n          parsedAttributes = JSON.parse(options.attributes) as Record<string, unknown>;\n        } catch (e) {\n          throw new CLIError(\"Invalid JSON in --attributes\", 1, [\n            \"Ensure your JSON is valid and properly formatted\",\n          ]);\n        }\n      } else if (attributePatch) {\n        // The element is the projected one when a changeset is active, so this merges over staged values.\n        parsedAttributes = resolveAttributeUpdate(elem.attributes, { attributePatch }, attributeFlags);\n      }\n\n      // Validate against schema using a temp element BEFORE mutating the live elem\n      if (resolvedNewType || parsedAttributes) {\n        const candidateType = resolvedNewType ?? elem.type;\n        const tempElem = new Element({\n          ...elem.toJSON(),\n          type: candidateType,\n          spec_node_id: `${layerName}.${candidateType}`,\n          attributes: parsedAttributes ?? elem.attributes,\n        });\n        const schemaValidator = new SchemaValidator();\n        const tempLayer = new Layer(layerName);\n        tempLayer.addElement(tempElem);\n        const attrValidation = await schemaValidator.validateLayer(tempLayer);\n        const undefinedTypeHint = undefinedTypeCheck(layerName, id, candidateType);\n        const blocking = undefinedTypeHint\n          ? attrValidation.errors.filter((e) => e.location !== \"/type\")\n          : attrValidation.errors;\n        if (blocking.length > 0) {\n          const errorMessages = blocking\n            .map((e) => `  ${e.message}`)\n            .join(\"\\n\");\n          throw new CLIError(\n            `Updated attributes fail schema validation:\\n${errorMessages}`,\n            1,\n            [\n              undefinedTypeHint\n                ? undefinedTypeHint.hint\n                : resolvedNewType\n                  ? \"Incompatible attributes must be manually cleaned up before changing type. \" +\n                    schemaLookupHint(\"cli\", layerName, candidateType)\n                  : schemaLookupHint(\"cli\", layerName, elem.type),\n            ]\n          );\n        }\n        if (undefinedTypeHint) handleWarning(undefinedTypeHint.message, [undefinedTypeHint.hint]);\n      }\n\n      // Validation passed \u2014 apply all mutations to live element\n      if (resolvedNewType) {\n        elem.type = resolvedNewType;\n        after.type = resolvedNewType;\n        elem.spec_node_id = `${layerName}.${resolvedNewType}`;\n        after.spec_node_id = `${layerName}.${resolvedNewType}`;\n      }\n\n      if (options.name) {\n        elem.name = options.name;\n        after.name = options.name;\n      }\n\n      if (options.description !== undefined) {\n        elem.description = options.description || undefined;\n        after.description = options.description || undefined;\n      }\n\n      if (parsedAttributes) {\n        elem.attributes = parsedAttributes;\n        after.attributes = parsedAttributes;\n      }\n\n      if (options.clearSourceReference) {\n        elem.setSourceReference(undefined);\n        setStagedSourceReference(after, undefined);\n      } else if (options.sourceFile) {\n        const newRef = buildSourceReference(options);\n        if (newRef) {\n          elem.setSourceReference(newRef);\n          setStagedSourceReference(after, newRef);\n        }\n      }\n\n      // Update element in layer graph to persist mutations\n      layer.updateElement(elem);\n    });\n\n    const changes: Record<string, unknown> = {};\n    if (options.type) changes.type = options.type;\n    if (options.name) changes.name = options.name;\n    if (options.description !== undefined) changes.description = options.description;\n    if (options.sourceFile) changes.source = options.sourceFile;\n    if (options.clearSourceReference) changes.source = \"cleared\";\n\n    const details: Record<string, unknown> = {\n      elementId: id,\n      layer: layerName,\n      name: element.name,\n      changes,\n      changedFields: handler.getChangedFields(),\n      // The active changeset adds this element: the update was folded into that add.\n      ...(handler.wasFoldedIntoAdd() ? { foldedIntoAdd: true } : {}),\n    };\n\n    handleSuccess(\n      `Updated ${handler.wasFoldedIntoAdd() ? \"staged \" : \"\"}element ${ansis.bold(id)}` +\n        (handler.getChangedFields().length > 0 ? ` (${handler.getChangedFields().join(\", \")})` : \"\"),\n      details,\n      { verbose: options.verbose }\n    );\n  } catch (error) {\n    if (isTelemetryEnabled && span) {\n      (span as any).recordException(error as Error);\n      (span as any).setStatus({ code: 2, message: (error as Error).message });\n    }\n    handleError(error);\n  } finally {\n    if (isTelemetryEnabled) {\n      endSpan(span);\n    }\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/commands/upgrade.js

@@ -3,8 +3,11 @@ import { confirm } from "@clack/prompts";
 import { findProjectRoot, getSpecReferencePath, getModelPath } from "../utils/project-paths.js";
 import { getCliVersion, getCliBundledSpecVersion, getInstalledSpecVersion, getModelSpecVersion } from "../utils/spec-version.js";
 import { MigrationRegistry } from "../core/migration-registry.js";
-import { installSpecReference } from "../utils/spec-installer.js";
 import { Model } from "../core/model.js";
+import { pendingCatalogMigrations } from "../core/catalog-migration.js";
+import { upgradeModel } from "../core/model-upgrade.js";
+import { summarizeRelationshipChanges } from "../core/relationship-migration.js";
+import { installSpecReference } from "../utils/spec-installer.js";
 import { ClaudeIntegrationManager } from "../integrations/claude-manager.js";
 import { CopilotIntegrationManager } from "../integrations/copilot-manager.js";
 import { getErrorMessage } from "../utils/errors.js";
@@ -178,6 +181,9 @@ Available migrations:`));
         toVersion: targetSpecVersion,
         details: migrationDetails
       });
+    } else {
+      const catalogAction = await buildCatalogAction(projectRoot, targetSpecVersion);
+      catalogAction && actions.push(catalogAction);
     }
     const { actions: integrationActions, upToDate: integrationUpToDate } = await buildIntegrationActions(cliVersion, options.force ?? !1);
     if (actions.push(...integrationActions), actions.length === 0) {
@@ -259,6 +265,27 @@ async function executeSpecUpgrade(projectRoot, action) {
     endSpan(operationSpan);
   }
 }
+async function buildCatalogAction(projectRoot, version) {
+  let pending;
+  try {
+    pending = await pendingCatalogMigrations(await Model.load(projectRoot, { lazyLoad: !1 }));
+  } catch (error) {
+    return console.log(ansis.yellow(`\u26A0 Could not check the model against the catalog: ${getErrorMessage(error)}`)), null;
+  }
+  const details = [
+    ...pending.elementTypes > 0 ? [`Rename ${pending.elementTypes} element(s) whose type was renamed`] : [],
+    ...pending.relationships > 0 ? [`Rewrite or drop ${pending.relationships} relationship(s) of retired types`] : [],
+    ...pending.stagedRelationships > 0 ? [`Rewrite ${pending.stagedRelationships} staged relationship change(s)`] : []
+  ];
+  return details.length === 0 ? null : {
+    type: "model",
+    description: `Apply catalog changes to the model (spec v${version})`,
+    fromVersion: version,
+    toVersion: version,
+    details,
+    catalogOnly: !0
+  };
+}
 async function executeModelMigration(action, options) {
   const operationSpan = isTelemetryEnabled ? startSpan("upgrade.model", {
     "upgrade.model.from_version": action.fromVersion || "unknown",
@@ -269,20 +296,24 @@ async function executeModelMigration(action, options) {
   try {
     if (action.versionBumpOnly) {
       console.log(ansis.dim(`Bumping model spec version from v${action.fromVersion} to v${action.toVersion}...`));
-      const model2 = await Model.load(process.cwd(), { lazyLoad: !0 });
-      model2.manifest.specVersion = action.toVersion, await model2.saveManifest(), console.log(ansis.green(`\u2713 Model spec version updated to v${action.toVersion}`)), operationSpan && operationSpan.setAttribute("upgrade.model.result", "version_bumped");
+      const result2 = await upgradeModel(process.cwd(), {
+        fromVersion: action.fromVersion,
+        toVersion: action.toVersion,
+        versionBumpOnly: !0
+      });
+      console.log(ansis.green(`\u2713 Model spec version updated to v${action.toVersion}`)), printChangesetRebaseline(result2.changesets), operationSpan && (operationSpan.setAttribute("upgrade.model.result", "version_bumped"), operationSpan.setAttribute("upgrade.model.changesets_rebaselined", result2.changesets.rebaselined.length));
       return;
     }
-    console.log(ansis.dim(`Migrating model from v${action.fromVersion} to v${action.toVersion}...`));
-    const model = await Model.load(process.cwd(), { lazyLoad: !1 }), result = await new MigrationRegistry().applyMigrations(model, {
+    console.log(ansis.dim(action.catalogOnly ? `Applying catalog changes to the model (v${action.toVersion})...` : `Migrating model from v${action.fromVersion} to v${action.toVersion}...`));
+    const result = await upgradeModel(process.cwd(), {
       fromVersion: action.fromVersion,
       toVersion: action.toVersion,
-      dryRun: !1,
-      validate: !options.force
-    });
-    for (const applied of result.applied)
-      console.log(ansis.green(`  \u2713 ${applied.from} \u2192 ${applied.to}: ${applied.description}`)), applied.changes?.filesModified && console.log(ansis.dim(`    Files modified: ${applied.changes.filesModified}`));
-    await model.saveManifest(), await model.saveDirtyLayers(), console.log(ansis.green(`\u2713 Model migrated to v${action.toVersion}`)), operationSpan && (operationSpan.setAttribute("upgrade.model.result", "migrated"), operationSpan.setAttribute("upgrade.model.migrations_applied", result.applied.length));
+      validate: !options.force,
+      catalogOnly: action.catalogOnly
+    }), applied = result.migration?.applied ?? [];
+    for (const migration of applied)
+      console.log(ansis.green(`  \u2713 ${migration.from} \u2192 ${migration.to}: ${migration.description}`)), migration.changes?.filesModified && console.log(ansis.dim(`    Files modified: ${migration.changes.filesModified}`)), printElementTypeChanges(migration.changes?.details?.elementTypeChanges), printRelationshipChanges(migration.changes?.details?.relationshipChanges), printStagedRelationshipChanges(migration.changes?.details?.stagedRelationshipChanges);
+    console.log(ansis.green(action.catalogOnly ? `\u2713 Model in line with the v${action.toVersion} catalog` : `\u2713 Model migrated to v${action.toVersion}`)), printChangesetRebaseline(result.changesets), operationSpan && (operationSpan.setAttribute("upgrade.model.result", "migrated"), operationSpan.setAttribute("upgrade.model.migrations_applied", applied.length), operationSpan.setAttribute("upgrade.model.changesets_rebaselined", result.changesets.rebaselined.length));
   } catch (error) {
     throw operationSpan && (operationSpan.recordException(error), operationSpan.setStatus({
       code: 2,
@@ -293,6 +324,63 @@ async function executeModelMigration(action, options) {
     endSpan(operationSpan);
   }
 }
+function printElementTypeChanges(changes) {
+  if (!Array.isArray(changes) || changes.length === 0)
+    return;
+  const byType = /* @__PURE__ */ new Map();
+  for (const c of changes) {
+    const key = `${c.fromType} \u2192 ${c.toType}`;
+    byType.set(key, (byType.get(key) ?? 0) + 1);
+  }
+  for (const [key, n] of byType)
+    console.log(ansis.dim(`    Renamed ${n} element(s): ${key}`));
+}
+function printRelationshipChanges(changes) {
+  if (!Array.isArray(changes) || changes.length === 0)
+    return;
+  const relationshipChanges = changes;
+  console.log(ansis.dim(`    ${summarizeRelationshipChanges(relationshipChanges)}`));
+  for (const change of relationshipChanges)
+    change.action === "dropped-duplicate" && change.after ? console.log(ansis.dim(`      dropped ${formatRelationship(change.before)} (now the same as ${formatRelationship(change.after)})`)) : change.action === "dropped" && console.log(ansis.dim(`      dropped ${formatRelationship(change.before)} (no replacement in the catalog)`));
+}
+function printStagedRelationshipChanges(changes) {
+  if (!Array.isArray(changes) || changes.length === 0)
+    return;
+  const byChangeset = /* @__PURE__ */ new Map();
+  for (const change of changes)
+    byChangeset.set(change.changeset, [...byChangeset.get(change.changeset) ?? [], change]);
+  for (const [changeset, staged] of byChangeset) {
+    console.log(ansis.dim(`    ${summarizeRelationshipChanges(staged, `changeset ${changeset}, staged relationships`)}`));
+    for (const change of staged) {
+      if (change.action === "rewritten")
+        continue;
+      const kind = change.stagedAs === "relationship-add" ? "add" : "delete";
+      console.log(ansis.dim(`      dropped staged ${kind} of ${formatRelationship(change.before)} (${stagedDropReason(change)})`));
+    }
+  }
+}
+function stagedDropReason(change) {
+  if (change.action === "dropped" || !change.after)
+    return "no replacement in the catalog";
+  const sameAs = `now the same as ${formatRelationship(change.after)}`;
+  switch (change.duplicateOf) {
+    case "model":
+      return `${sameAs}, already in the model`;
+    case "kept":
+      return `${sameAs}, which also stands for a relationship the changeset keeps`;
+    default:
+      return change.stagedAs === "relationship-add" ? `${sameAs}, which the changeset already adds` : `${sameAs}, which the changeset already deletes`;
+  }
+}
+function formatRelationship(rel) {
+  return `${rel.source} --[${rel.predicate}]--> ${rel.target}`;
+}
+function printChangesetRebaseline(result) {
+  const names = (refs) => refs.map((ref) => ref.name).join(", "), count = (n) => `${n} staged changeset${n === 1 ? "" : "s"}`;
+  result.rebaselined.length > 0 && console.log(ansis.green(`\u2713 Re-baselined ${count(result.rebaselined.length)} on the upgraded model: ${names(result.rebaselined)}`)), result.drifted.length > 0 && console.log(ansis.yellow(`\u26A0 ${count(result.drifted.length)} had drifted from the model before the upgrade and still ${result.drifted.length === 1 ? "needs" : "need"} --force to commit: ${names(result.drifted)}`));
+  for (const error of result.errors)
+    console.log(ansis.yellow(`\u26A0 ${error}`));
+}
 async function executeIntegrationUpdate(label, updateFn) {
   const operationSpan = isTelemetryEnabled ? startSpan("upgrade.integration", {
     "upgrade.integration.label": label,