obsidian-accomplishments-mcp 0.1.9 → 0.1.11

package/dist/tools/entity-management-tools.js

@@ -0,0 +1,851 @@
+/**
+ * V2 Entity Management Tools
+ *
+ * MCP tools for creating, updating, archiving, and restoring entities.
+ */
+import { generateCssClasses } from '../services/v2/entity-serializer.js';
+import { workstreamNormalizer } from '../services/v2/workstream-normalizer.js';
+// =============================================================================
+// Relationship Validation Constants
+// =============================================================================
+/**
+ * Valid target types for Decision.affects field.
+ * Decisions can affect: documents, stories, tasks (NOT milestones)
+ */
+const DECISION_AFFECTS_VALID_TYPES = ['document', 'story', 'task'];
+/**
+ * Valid target types for Document.implemented_by field.
+ * Documents can be implemented by: stories, tasks (NOT milestones)
+ */
+const DOCUMENT_IMPLEMENTED_BY_VALID_TYPES = ['story', 'task'];
+/**
+ * Valid target types for depends_on fields by entity type.
+ */
+const DEPENDS_ON_VALID_TYPES = {
+    milestone: ['milestone', 'decision'],
+    story: ['story', 'decision', 'document'],
+    task: ['task', 'decision'],
+    decision: ['decision'],
+    document: ['document', 'decision'],
+    feature: ['feature', 'decision'],
+};
+/**
+ * Validate entity relationships before creation/update.
+ * Checks that:
+ * 1. All referenced entity IDs exist (or are in the batch being created)
+ * 2. Relationship types are valid (e.g., decisions can't enable milestones)
+ *
+ * @param type - The entity type being created/updated
+ * @param data - The entity data containing relationships
+ * @param deps - Dependencies for entity lookup
+ * @param batchIds - Optional map of IDs being created in the same batch (id -> type)
+ */
+export function validateRelationships(type, data, deps, batchIds) {
+    const errors = [];
+    // Helper to check if an ID exists (in cache or batch)
+    const idExists = (id) => {
+        return deps.entityExists(id) || (batchIds?.has(id) ?? false);
+    };
+    // Helper to get entity type (from cache or batch)
+    const getType = (id) => {
+        const cachedType = deps.getEntityType(id);
+        if (cachedType)
+            return cachedType;
+        return batchIds?.get(id) ?? null;
+    };
+    // Validate parent reference
+    const parent = data.parent;
+    if (parent) {
+        if (!idExists(parent)) {
+            errors.push({
+                field: 'parent',
+                message: `Parent entity '${parent}' does not exist`,
+                invalidId: parent,
+            });
+        }
+        else {
+            // Validate parent type
+            const parentType = getType(parent);
+            if (type === 'story' && parentType && parentType !== 'milestone') {
+                errors.push({
+                    field: 'parent',
+                    message: `Story parent must be a milestone, got '${parentType}'`,
+                    invalidId: parent,
+                });
+            }
+            if (type === 'task' && parentType && parentType !== 'story') {
+                errors.push({
+                    field: 'parent',
+                    message: `Task parent must be a story, got '${parentType}'`,
+                    invalidId: parent,
+                });
+            }
+        }
+    }
+    // Validate depends_on references
+    const dependsOn = data.depends_on;
+    if (dependsOn && dependsOn.length > 0) {
+        const validTypes = DEPENDS_ON_VALID_TYPES[type];
+        for (const depId of dependsOn) {
+            if (!idExists(depId)) {
+                errors.push({
+                    field: 'depends_on',
+                    message: `Dependency '${depId}' does not exist`,
+                    invalidId: depId,
+                });
+            }
+            else {
+                const depType = getType(depId);
+                if (depType && !validTypes.includes(depType)) {
+                    errors.push({
+                        field: 'depends_on',
+                        message: `${type} cannot depend on ${depType} '${depId}'. Valid types: ${validTypes.join(', ')}`,
+                        invalidId: depId,
+                    });
+                }
+            }
+        }
+    }
+    // Validate implements references (for stories and milestones)
+    const implementsField = data.implements;
+    if (implementsField && implementsField.length > 0) {
+        for (const implId of implementsField) {
+            if (!idExists(implId)) {
+                errors.push({
+                    field: 'implements',
+                    message: `Document '${implId}' does not exist`,
+                    invalidId: implId,
+                });
+            }
+            else {
+                const implType = getType(implId);
+                if (implType && implType !== 'document') {
+                    errors.push({
+                        field: 'implements',
+                        message: `Can only implement documents, got ${implType} '${implId}'`,
+                        invalidId: implId,
+                    });
+                }
+            }
+        }
+    }
+    // Validate affects references (for decisions)
+    if (type === 'decision') {
+        const affects = data.affects;
+        if (affects && affects.length > 0) {
+            for (const affectedId of affects) {
+                if (!idExists(affectedId)) {
+                    errors.push({
+                        field: 'affects',
+                        message: `Entity '${affectedId}' does not exist`,
+                        invalidId: affectedId,
+                    });
+                }
+                else {
+                    const affectedType = getType(affectedId);
+                    if (affectedType && !DECISION_AFFECTS_VALID_TYPES.includes(affectedType)) {
+                        errors.push({
+                            field: 'affects',
+                            message: `Decision cannot affect ${affectedType} '${affectedId}'. Valid types: ${DECISION_AFFECTS_VALID_TYPES.join(', ')}`,
+                            invalidId: affectedId,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Validate implemented_by references (for documents)
+    if (type === 'document') {
+        const implementedBy = data.implemented_by;
+        if (implementedBy && implementedBy.length > 0) {
+            for (const implById of implementedBy) {
+                if (!idExists(implById)) {
+                    errors.push({
+                        field: 'implemented_by',
+                        message: `Entity '${implById}' does not exist`,
+                        invalidId: implById,
+                    });
+                }
+                else {
+                    const implByType = getType(implById);
+                    if (implByType && !DOCUMENT_IMPLEMENTED_BY_VALID_TYPES.includes(implByType)) {
+                        errors.push({
+                            field: 'implemented_by',
+                            message: `Document cannot be implemented by ${implByType} '${implById}'. Valid types: ${DOCUMENT_IMPLEMENTED_BY_VALID_TYPES.join(', ')}`,
+                            invalidId: implById,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Validate supersedes reference (for decisions)
+    if (type === 'decision') {
+        const supersedes = data.supersedes;
+        if (supersedes) {
+            if (!idExists(supersedes)) {
+                errors.push({
+                    field: 'supersedes',
+                    message: `Decision '${supersedes}' does not exist`,
+                    invalidId: supersedes,
+                });
+            }
+            else {
+                const supersedesType = getType(supersedes);
+                if (supersedesType && supersedesType !== 'decision') {
+                    errors.push({
+                        field: 'supersedes',
+                        message: `Can only supersede decisions, got ${supersedesType} '${supersedes}'`,
+                        invalidId: supersedes,
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+/**
+ * Create a new entity with optional dependencies and relationships.
+ */
+export async function createEntity(input, deps) {
+    const { type, data, options } = input;
+    // Validate relationships before creating
+    const validationErrors = validateRelationships(type, data, deps);
+    if (validationErrors.length > 0) {
+        const errorMessages = validationErrors.map(e => `${e.field}: ${e.message}`).join('; ');
+        throw new Error(`Invalid relationships: ${errorMessages}`);
+    }
+    // Normalize workstream
+    const workstreamResult = workstreamNormalizer.normalize(data.workstream);
+    const normalizedWorkstream = workstreamResult.normalized;
+    // Generate new ID
+    const id = await deps.getNextId(type);
+    // Build base entity
+    const now = deps.getCurrentTimestamp();
+    const baseEntity = {
+        id,
+        type,
+        title: data.title,
+        workstream: normalizedWorkstream,
+        created_at: now,
+        updated_at: now,
+        archived: false,
+        canvas_source: options?.canvas_source,
+    };
+    // Build type-specific entity
+    let entity;
+    switch (type) {
+        case 'milestone':
+            entity = buildMilestone(baseEntity, data);
+            break;
+        case 'story':
+            entity = buildStory(baseEntity, data);
+            break;
+        case 'task':
+            entity = buildTask(baseEntity, data);
+            break;
+        case 'decision':
+            entity = buildDecision(baseEntity, data);
+            break;
+        case 'document':
+            entity = buildDocument(baseEntity, data);
+            break;
+        case 'feature':
+            entity = buildFeature(baseEntity, data);
+            break;
+        default:
+            throw new Error(`Unknown entity type: ${type}`);
+    }
+    // Write entity to file
+    await deps.writeEntity(entity);
+    // Add to canvas if requested
+    let canvasNodeAdded = false;
+    if (options?.add_to_canvas !== false && deps.addToCanvas && options?.canvas_source) {
+        canvasNodeAdded = await deps.addToCanvas(entity, options.canvas_source);
+    }
+    // Convert to full representation
+    const entityFull = await deps.toEntityFull(entity);
+    // Build result with optional normalization message
+    const result = {
+        id,
+        entity: entityFull,
+        dependencies_created: data.depends_on?.length ?? 0,
+        canvas_node_added: canvasNodeAdded,
+    };
+    // Add normalization message if workstream was normalized
+    if (workstreamResult.wasNormalized && workstreamResult.message) {
+        result.messages = result.messages || [];
+        result.messages.push(workstreamResult.message);
+    }
+    return result;
+}
+// =============================================================================
+// Entity Builders
+// =============================================================================
+function buildMilestone(base, data) {
+    const entity = {
+        ...base,
+        type: 'milestone',
+        status: data.status || 'Not Started',
+        priority: data.priority,
+        target_date: data.target_date,
+        owner: data.owner,
+        depends_on: data.depends_on || [],
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+function buildStory(base, data) {
+    const entity = {
+        ...base,
+        type: 'story',
+        status: data.status || 'Not Started',
+        parent: data.parent,
+        priority: data.priority,
+        depends_on: data.depends_on || [],
+        implements: data.implements || [],
+        acceptance_criteria: data.acceptance_criteria || [],
+        tasks: data.tasks || [],
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+function buildTask(base, data) {
+    const entity = {
+        ...base,
+        type: 'task',
+        status: data.status || 'Not Started',
+        parent: data.parent,
+        goal: data.goal || '',
+        estimate_hrs: data.estimate_hrs,
+        actual_hrs: data.actual_hrs,
+        assignee: data.assignee,
+        description: data.description,
+        technical_notes: data.technical_notes,
+        notes: data.notes,
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+function buildDecision(base, data) {
+    const entity = {
+        ...base,
+        type: 'decision',
+        status: data.status || 'Pending',
+        decided_by: data.decided_by,
+        decided_on: data.decided_on,
+        supersedes: data.supersedes,
+        affects: data.affects || [],
+        depends_on: data.depends_on || [],
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+function buildDocument(base, data) {
+    const entity = {
+        ...base,
+        type: 'document',
+        doc_type: data.doc_type || 'spec',
+        status: data.status || 'Draft',
+        version: data.version,
+        owner: data.owner,
+        implementation_context: data.implementation_context,
+        implemented_by: data.implemented_by || [],
+        previous_version: data.previous_version || [],
+        content: data.content,
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+function buildFeature(base, data) {
+    const entity = {
+        ...base,
+        type: 'feature',
+        status: data.status || 'Planned',
+        user_story: data.user_story || '',
+        tier: data.tier || 'OSS',
+        phase: data.phase || 'MVP',
+        implemented_by: data.implemented_by || [],
+        documented_by: data.documented_by || [],
+        decided_by: data.decided_by || [],
+        test_refs: data.test_refs || [],
+        content: data.content,
+    };
+    // Auto-generate cssclasses if not provided
+    entity.cssclasses = data.cssclasses || generateCssClasses(entity);
+    return entity;
+}
+// =============================================================================
+// Update Entity (Enhanced - consolidates status, archive, restore operations)
+// =============================================================================
+/**
+ * Update entity fields and/or modify relationships.
+ * Enhanced to support:
+ * - Status updates with validation and cascade (replaces update_entity_status)
+ * - Archive operations (replaces archive_entity, archive_milestone)
+ * - Restore operations (replaces restore_from_archive)
+ */
+export async function updateEntity(input, deps) {
+    const { id, data, add_dependencies, remove_dependencies, add_to, remove_from, status, status_note, cascade, archived, archive_options, restore_options, } = input;
+    // Get existing entity
+    const entity = await deps.getEntity(id);
+    if (!entity) {
+        throw new Error(`Entity not found: ${id}`);
+    }
+    // Initialize result
+    const result = {
+        id,
+        entity: null, // Will be set at the end
+        dependencies_added: 0,
+        dependencies_removed: 0,
+    };
+    // Handle archive operation (takes precedence)
+    if (archived === true) {
+        const archiveResult = await handleArchiveOperation(entity, archive_options, deps);
+        result.archive_result = archiveResult;
+        // After archiving, get the updated entity
+        const archivedEntity = await deps.getEntity(id);
+        if (archivedEntity) {
+            result.entity = await deps.toEntityFull(archivedEntity);
+        }
+        return result;
+    }
+    // Handle restore operation
+    if (archived === false && entity.archived) {
+        const restoreResult = await handleRestoreOperation(entity, restore_options, deps);
+        result.restore_result = restoreResult;
+        // After restoring, get the updated entity
+        const restoredEntity = await deps.getEntity(id);
+        if (restoredEntity) {
+            result.entity = await deps.toEntityFull(restoredEntity);
+        }
+        return result;
+    }
+    // Apply field updates
+    const updatedEntity = { ...entity };
+    let workstreamNormalizationMessage;
+    if (data) {
+        // Normalize workstream if being updated
+        if (data.workstream !== undefined) {
+            const workstreamResult = workstreamNormalizer.normalize(data.workstream);
+            data.workstream = workstreamResult.normalized;
+            if (workstreamResult.wasNormalized && workstreamResult.message) {
+                workstreamNormalizationMessage = workstreamResult.message;
+            }
+        }
+        Object.assign(updatedEntity, data);
+    }
+    // Handle status update with validation and cascade
+    if (status && status !== entity.status) {
+        const statusResult = await handleStatusUpdate(entity, status, status_note, cascade, deps);
+        result.status_changed = statusResult;
+        updatedEntity.status = status;
+    }
+    // Handle dependency changes
+    if ('depends_on' in updatedEntity) {
+        const currentDeps = updatedEntity.depends_on || [];
+        if (add_dependencies) {
+            const newDeps = [...new Set([...currentDeps, ...add_dependencies])];
+            updatedEntity.depends_on = newDeps;
+            result.dependencies_added = newDeps.length - currentDeps.length;
+        }
+        if (remove_dependencies) {
+            const filtered = currentDeps.filter((d) => !remove_dependencies.includes(d));
+            updatedEntity.depends_on = filtered;
+            result.dependencies_removed = currentDeps.length - filtered.length;
+        }
+    }
+    // Handle relationship additions (implements, affects)
+    if (add_to) {
+        if (add_to.implements && 'implements' in updatedEntity) {
+            const current = updatedEntity.implements || [];
+            updatedEntity.implements = [...new Set([...current, ...add_to.implements])];
+        }
+        if (add_to.affects && 'affects' in updatedEntity) {
+            const current = updatedEntity.affects || [];
+            updatedEntity.affects = [...new Set([...current, ...add_to.affects])];
+        }
+    }
+    // Handle relationship removals
+    if (remove_from) {
+        if (remove_from.implements && 'implements' in updatedEntity) {
+            const current = updatedEntity.implements || [];
+            updatedEntity.implements = current.filter((i) => !remove_from.implements.includes(i));
+        }
+        if (remove_from.affects && 'affects' in updatedEntity) {
+            const current = updatedEntity.affects || [];
+            updatedEntity.affects = current.filter((e) => !remove_from.affects.includes(e));
+        }
+    }
+    // Update timestamp
+    updatedEntity.updated_at = deps.getCurrentTimestamp();
+    // Compute field changes (before/after diff)
+    const changes = computeFieldChanges(entity, updatedEntity);
+    if (changes.length > 0) {
+        result.changes = changes;
+    }
+    // Write updated entity
+    await deps.writeEntity(updatedEntity);
+    // Convert to full representation
+    result.entity = await deps.toEntityFull(updatedEntity);
+    // Add normalization message if workstream was normalized
+    if (workstreamNormalizationMessage) {
+        result.messages = result.messages || [];
+        result.messages.push(workstreamNormalizationMessage);
+    }
+    return result;
+}
+// =============================================================================
+// Helper: Compute Field Changes (before/after diff)
+// =============================================================================
+/**
+ * Compare two entity states and return a list of field changes.
+ * For array fields, also computes added/removed items.
+ */
+function computeFieldChanges(before, after) {
+    const changes = [];
+    // Get all keys from both objects
+    const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    // Fields to skip (internal/computed)
+    const skipFields = new Set(['vault_path', 'created_at', 'updated_at']);
+    for (const key of allKeys) {
+        if (skipFields.has(key))
+            continue;
+        const beforeVal = before[key];
+        const afterVal = after[key];
+        // Check if values are different
+        const beforeStr = JSON.stringify(beforeVal);
+        const afterStr = JSON.stringify(afterVal);
+        if (beforeStr !== afterStr) {
+            const change = {
+                field: key,
+                before: beforeVal,
+                after: afterVal,
+            };
+            // For arrays, compute added/removed
+            if (Array.isArray(beforeVal) || Array.isArray(afterVal)) {
+                const beforeArr = Array.isArray(beforeVal) ? beforeVal : [];
+                const afterArr = Array.isArray(afterVal) ? afterVal : [];
+                const beforeSet = new Set(beforeArr.map(v => JSON.stringify(v)));
+                const afterSet = new Set(afterArr.map(v => JSON.stringify(v)));
+                const added = afterArr.filter(v => !beforeSet.has(JSON.stringify(v)));
+                const removed = beforeArr.filter(v => !afterSet.has(JSON.stringify(v)));
+                if (added.length > 0)
+                    change.added = added;
+                if (removed.length > 0)
+                    change.removed = removed;
+            }
+            changes.push(change);
+        }
+    }
+    return changes;
+}
+// =============================================================================
+// Helper: Handle Status Update
+// =============================================================================
+async function handleStatusUpdate(entity, newStatus, note, cascade, deps) {
+    const oldStatus = entity.status;
+    // Validate transition
+    const validation = deps.validateStatusTransition(entity, newStatus);
+    if (!validation.valid) {
+        throw new Error(`Invalid status transition: ${validation.reason}`);
+    }
+    // Compute cascade effects if requested
+    let cascadedUpdates = [];
+    if (cascade) {
+        cascadedUpdates = await deps.computeCascadeEffects(entity, newStatus);
+    }
+    return {
+        old_status: oldStatus,
+        new_status: newStatus,
+        cascaded_updates: cascadedUpdates,
+    };
+}
+// =============================================================================
+// Helper: Handle Archive Operation
+// =============================================================================
+async function handleArchiveOperation(entity, options, deps) {
+    const { force, cascade: archiveCascade, archive_folder, remove_from_canvas, canvas_source } = options || {};
+    // For milestones with cascade, archive all children
+    if (entity.type === 'milestone' && archiveCascade) {
+        const archivedChildren = [];
+        // Compute archive path
+        const now = new Date();
+        const quarter = Math.ceil((now.getMonth() + 1) / 3);
+        const archivePath = archive_folder || `archive/${now.getFullYear()}-Q${quarter}`;
+        // Get all children (stories)
+        const stories = await deps.getChildren(entity.id);
+        for (const story of stories) {
+            // Get tasks for each story
+            const tasks = await deps.getChildren(story.id);
+            for (const task of tasks) {
+                await deps.moveToArchive(task.id, archivePath);
+                archivedChildren.push(task.id);
+                if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+                    await deps.removeFromCanvas(task.id, canvas_source);
+                }
+            }
+            await deps.moveToArchive(story.id, archivePath);
+            archivedChildren.push(story.id);
+            if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+                await deps.removeFromCanvas(story.id, canvas_source);
+            }
+        }
+        // Archive the milestone itself
+        const finalPath = await deps.moveToArchive(entity.id, archivePath);
+        if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+            await deps.removeFromCanvas(entity.id, canvas_source);
+        }
+        return {
+            archived: true,
+            archive_path: finalPath,
+            archived_children: archivedChildren,
+        };
+    }
+    // For non-cascade archive, check for children
+    if (!force) {
+        const children = await deps.getChildren(entity.id);
+        if (children.length > 0) {
+            throw new Error(`Entity has ${children.length} children. Use archive_options.force=true to archive anyway, or archive_options.cascade=true to archive children.`);
+        }
+    }
+    // Move to archive
+    const finalPath = await deps.moveToArchive(entity.id, archive_folder);
+    // Remove from canvas if requested
+    if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+        await deps.removeFromCanvas(entity.id, canvas_source);
+    }
+    return {
+        archived: true,
+        archive_path: finalPath,
+    };
+}
+// =============================================================================
+// Helper: Handle Restore Operation
+// =============================================================================
+async function handleRestoreOperation(entity, options, deps) {
+    const { restore_children, add_to_canvas, canvas_source } = options || {};
+    // Restore the entity
+    await deps.restoreFromArchive(entity.id);
+    // Add to canvas if requested
+    if (add_to_canvas && deps.addToCanvas && canvas_source) {
+        const restoredEntity = await deps.getEntity(entity.id);
+        if (restoredEntity) {
+            await deps.addToCanvas(restoredEntity, canvas_source);
+        }
+    }
+    // Restore children if requested
+    const restoredChildren = [];
+    if (restore_children) {
+        const children = await deps.getChildren(entity.id);
+        for (const child of children) {
+            await deps.restoreFromArchive(child.id);
+            restoredChildren.push(child.id);
+            if (add_to_canvas && deps.addToCanvas && canvas_source) {
+                await deps.addToCanvas(child, canvas_source);
+            }
+            // Also restore grandchildren (tasks under stories)
+            const grandchildren = await deps.getChildren(child.id);
+            for (const grandchild of grandchildren) {
+                await deps.restoreFromArchive(grandchild.id);
+                restoredChildren.push(grandchild.id);
+                if (add_to_canvas && deps.addToCanvas && canvas_source) {
+                    await deps.addToCanvas(grandchild, canvas_source);
+                }
+            }
+        }
+    }
+    return {
+        restored: true,
+        restored_children: restoredChildren.length > 0 ? restoredChildren : undefined,
+    };
+}
+// =============================================================================
+// Update Entity Status (DEPRECATED - use updateEntity with status field)
+// =============================================================================
+/**
+ * @deprecated Use updateEntity({ id, status, status_note, cascade }) instead.
+ * Dedicated status update with optional note and cascade.
+ */
+export async function updateEntityStatus(input, deps) {
+    const { id, status, note, cascade } = input;
+    // Get existing entity
+    const entity = await deps.getEntity(id);
+    if (!entity) {
+        throw new Error(`Entity not found: ${id}`);
+    }
+    const oldStatus = entity.status;
+    // Validate transition
+    const validation = deps.validateStatusTransition(entity, status);
+    if (!validation.valid) {
+        throw new Error(`Invalid status transition: ${validation.reason}`);
+    }
+    // Update entity - cast to Entity to handle status type variance
+    const updatedEntity = {
+        ...entity,
+        status,
+        updated_at: deps.getCurrentTimestamp(),
+    };
+    // Add note to content if provided
+    if (note) {
+        // Note: In a real implementation, this would append to the entity's notes section
+        // For now, we just update the entity
+    }
+    // Write updated entity
+    await deps.writeEntity(updatedEntity);
+    // Compute cascade effects if requested
+    let cascadedUpdates = [];
+    if (cascade) {
+        cascadedUpdates = await deps.computeCascadeEffects(updatedEntity, status);
+    }
+    return {
+        id,
+        old_status: oldStatus,
+        new_status: status,
+        cascaded_updates: cascadedUpdates,
+    };
+}
+// =============================================================================
+// Archive Entity (DEPRECATED - use updateEntity with archived: true)
+// =============================================================================
+/**
+ * @deprecated Use updateEntity({ id, archived: true, archive_options }) instead.
+ * Archive a single entity.
+ */
+export async function archiveEntity(input, deps) {
+    const { id, force, remove_from_canvas, canvas_source } = input;
+    // Get existing entity
+    const entity = await deps.getEntity(id);
+    if (!entity) {
+        throw new Error(`Entity not found: ${id}`);
+    }
+    // Check for children if not forcing
+    if (!force) {
+        const children = await deps.getChildren(id);
+        if (children.length > 0) {
+            throw new Error(`Entity has ${children.length} children. Use force=true to archive anyway.`);
+        }
+    }
+    // Move to archive (runtime handles path computation based on config)
+    const finalPath = await deps.moveToArchive(id);
+    // Remove from canvas if requested
+    if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+        await deps.removeFromCanvas(id, canvas_source);
+    }
+    return {
+        id,
+        archived: true,
+        archive_path: finalPath,
+    };
+}
+// =============================================================================
+// Archive Milestone (DEPRECATED - use updateEntity with archived: true, archive_options.cascade: true)
+// =============================================================================
+/**
+ * @deprecated Use updateEntity({ id, archived: true, archive_options: { cascade: true } }) instead.
+ * Archive a milestone and all its children.
+ */
+export async function archiveMilestone(input, deps) {
+    const { milestone_id, archive_folder, remove_from_canvas, canvas_source } = input;
+    // Get milestone
+    const milestone = await deps.getEntity(milestone_id);
+    if (!milestone) {
+        throw new Error(`Milestone not found: ${milestone_id}`);
+    }
+    if (milestone.type !== 'milestone') {
+        throw new Error(`Entity ${milestone_id} is not a milestone`);
+    }
+    // Compute archive path
+    const now = new Date();
+    const quarter = Math.ceil((now.getMonth() + 1) / 3);
+    const archivePath = archive_folder || `archive/${now.getFullYear()}-Q${quarter}`;
+    // Collect all entities to archive
+    const archivedMilestones = [milestone_id];
+    const archivedStories = [];
+    const archivedTasks = [];
+    // Get all children (stories)
+    const stories = await deps.getChildren(milestone_id);
+    for (const story of stories) {
+        archivedStories.push(story.id);
+        // Get tasks for each story
+        const tasks = await deps.getChildren(story.id);
+        for (const task of tasks) {
+            archivedTasks.push(task.id);
+        }
+    }
+    // Archive all entities and remove from canvas
+    const allIds = [...archivedTasks, ...archivedStories, ...archivedMilestones];
+    for (const id of allIds) {
+        await deps.moveToArchive(id, archivePath);
+        // Remove from canvas if requested
+        if (remove_from_canvas && deps.removeFromCanvas && canvas_source) {
+            await deps.removeFromCanvas(id, canvas_source);
+        }
+    }
+    return {
+        milestone_id,
+        archived_entities: {
+            milestones: archivedMilestones,
+            stories: archivedStories,
+            tasks: archivedTasks,
+        },
+        total_archived: archivedMilestones.length + archivedStories.length + archivedTasks.length,
+        archive_path: archivePath,
+    };
+}
+// =============================================================================
+// Restore From Archive (DEPRECATED - use updateEntity with archived: false)
+// =============================================================================
+/**
+ * @deprecated Use updateEntity({ id, archived: false, restore_options }) instead.
+ * Restore an archived entity.
+ */
+export async function restoreFromArchive(input, deps) {
+    const { id, restore_children, add_to_canvas, canvas_source } = input;
+    // Restore the entity
+    await deps.restoreFromArchive(id);
+    // Add to canvas if requested
+    if (add_to_canvas && deps.addToCanvas && canvas_source) {
+        const entity = await deps.getEntity(id);
+        if (entity) {
+            await deps.addToCanvas(entity, canvas_source);
+        }
+    }
+    // Restore children if requested
+    const restoredChildren = [];
+    if (restore_children) {
+        const children = await deps.getChildren(id);
+        for (const child of children) {
+            await deps.restoreFromArchive(child.id);
+            restoredChildren.push(child.id);
+            // Add child to canvas if requested
+            if (add_to_canvas && deps.addToCanvas && canvas_source) {
+                await deps.addToCanvas(child, canvas_source);
+            }
+            // Also restore grandchildren (tasks under stories)
+            const grandchildren = await deps.getChildren(child.id);
+            for (const grandchild of grandchildren) {
+                await deps.restoreFromArchive(grandchild.id);
+                restoredChildren.push(grandchild.id);
+                // Add grandchild to canvas if requested
+                if (add_to_canvas && deps.addToCanvas && canvas_source) {
+                    await deps.addToCanvas(grandchild, canvas_source);
+                }
+            }
+        }
+    }
+    return {
+        id,
+        restored: true,
+        restored_children: restoredChildren,
+    };
+}
+//# sourceMappingURL=entity-management-tools.js.map