CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.13.0 (2026-02-13)

Features

• ai-agent-skills: add documentation for reusable agent skills and installation instructions (49242f1)

Documentation

• archi-mcp-modeling: remove unnecessary code block from SKILL.md (989de80)

1.12.0 (2026-02-13)

Features

• archi-mcp-modeling: enhance documentation for idempotency and upsert operations (7c9078f)

1.11.0 (2026-02-13)

Features

• archi-mcp-modeling: add JArchi to ArchiMate concept mapping reference document (ae24520)
• idempotency: implement in-memory idempotency store for /model/apply operations (ae24520)
• routing: add progressive discovery workflow and mandatory loading order (9b2738d)

Bug Fixes

• integration: resolve idempotency/upsert integration issues with detailed root cause analysis (ae24520)

Documentation

• prd: create Product Requirements Document for MCP tooling improvements (ae24520)

[Unreleased]

Server/API

• add first-class /model/apply idempotency (idempotencyKey) with 24h in-memory TTL/LRU replay store and 409 IdempotencyConflict on payload hash mismatch
• add request-level duplicateStrategy (error|reuse|rename) and per-operation onDuplicate precedence for upsert operations
• add upsert operations createOrGetElement and createOrGetRelationship with explicit match contracts and deterministic action results (created|reused|renamed)
• add validation/error codes: InvalidDuplicateStrategy, InvalidMatchSpecification, AmbiguousMatch, IdempotencyConflict

MCP

• extend archi_apply_model_changes input contract with idempotencyKey and duplicateStrategy
• add support for createOrGetElement and createOrGetRelationship operation types
• derive deterministic per-chunk idempotency keys in MCP auto-chunk mode: ${idempotencyKey}:chunk:${index}:of:${total}

CLI

• add batch apply --idempotency-key <key> and --duplicate-strategy <error|reuse|rename>
• reject combining --skip-existing with --duplicate-strategy; mark --skip-existing as deprecated compatibility mode
• extend BOM/apply docs and schemas for new upsert operations and idempotency/duplicate-strategy behavior

1.9.0 (2026-02-12)

Features

• archi-mcp-modeling: add new skill for ArchiMate modeling (e594fc1)
• endpoints: enhance viewpoint resolution and normalization logic (3eb316b)
• logTab: create log tab with clear and export functionality (3eb316b)
• mcp-builder: add Python MCP server implementation guide and evaluation scripts (65e9438)
• monitorUI: implement tabbed interface for log, settings, and stats (3eb316b)
• operationValidation: simplify viewpoint format validation (3eb316b)
• settingsTab: add settings tab for server configuration management (3eb316b)
• statsTab: implement stats tab for live server metrics and operation stats (3eb316b)

Tests

• model-apply: add test for creating view with viewpoint as label (3eb316b)

1.8.1 (2026-02-11)

Maintenance

• readme: remove obsolete skills and commands sections (9b070f5)

1.8.0 (2026-02-11)

Features

• added banking example (99e01ee)
• completion: update completion command to use --raw option for direct script output (292f18e)
• docs: clarify --resolve-names behavior and deprecate --size option in batch commands (e37cd29)

Bug Fixes

• doctor: remove unnecessary --poll flag from examples (292f18e)
• ids: clarify polling behavior in ID mappings description (292f18e)
• ops: update help text to reflect default polling behavior in batch apply (292f18e)
• references: update accessType values and reorganize BOM reference for clarity (bf03b12)
• verify: add remediation guidance for incomplete ID files (292f18e)

Documentation

• init: update apply/poll cycle instructions for clarity (292f18e)
• openapi: clarify batch apply behavior in OpenAPI documentation (292f18e)
• readme: add comprehensive README for archicli with usage examples (292f18e)

Maintenance

• experience: delete outdated experience report for archicli (cc02a3b)
• skill-creator: remove obsolete skill creation scripts and documentation (0d12aff)
• todos: remove completed TODO item for archicli health command (cc02a3b)

Code Refactoring

• init: improve target directory resolution logic and output structure (292f18e)

Tests

• docs-option-parity: ensure command snippets use supported options (292f18e)
• first-run-workflow: validate onboarding workflow for archicli (292f18e)
• poll-and-completion-ux: verify polling behavior and completion command ergonomics (292f18e)
• quiet-mode-contract: ensure quiet mode returns expected data-only outputs (292f18e)

1.7.0 (2026-02-11)

Features

• completion: enhance completion vocabulary and scripts for new commands (f3bd39b)
• doctor: add preflight diagnostics command for server and model readiness (1f0c314)
• init: implement command to create starter BOM templates and workflow README (1f0c314)
• view: normalize view list response for legacy and envelope formats (f3bd39b)
• warnings: introduce structured warning handling for non-fatal issues (1f0c314)

Bug Fixes

• modelEndpoints: improve model file path resolution and error handling (f3bd39b)

Documentation

• add remaining work backlog and experience report for archicli (f3bd39b)

Maintenance

• archicli: update version to 1.6.0 in package-lock.json (8e876c2)
• server: update server version to 1.6.1 (63c12f1)

Code Refactoring

• api: log request details as warnings instead of stderr (1f0c314)
• health: remove text output mode for health command (1f0c314)
• ids: streamline output handling in IDs command (1f0c314)
• model: adjust output handling in model save command (1f0c314)
• output: capture and include warnings in CLI output (1f0c314)
• poll: log rate limit warnings during polling (1f0c314)
• verify: enhance output structure for verification results (1f0c314)
• view: simplify view command output handling (1f0c314)
• view: unify output handling in view commands (1f0c314)

Tests

• completion: add tests for completion vocabulary and script generation (f3bd39b)
• init: add tests for init command functionality (1f0c314)
• output: verify structured output for warnings (1f0c314)
• readme: ensure all commands are documented in README (1f0c314)
• view: add tests for normalizeViewListResponse function (f3bd39b)

1.6.1 (2026-02-11)

Maintenance

• remove empty code change entries from changes log (38e45ac)

1.6.0 (2026-02-10)

Features

• enhance CLI command structure with detailed documentation and error handling (208d6d9)

Bug Fixes

• batch apply robustness — op-aligned chunking, post-exec ID capture, cross-validation (621891d)

Maintenance

• apply local changes (0e8dd30)
• remove empty code change entries from changes log (0c1a961)

Code Refactoring

• api: remove unused PUT function and clean up server helper methods (530a56c)

1.5.0 (2026-02-10)

Features

• apply: add safe mode option and reduce default chunk size for batch apply command (aa50f2e)
• cli: implement client-side visual ID cross-validation for addConnectionToView operations (e978938)
• cli: remove --poll option from batch apply commands for default atomic behavior (e978938)
• skills: add skill-creator and consolidate archimate skills (7c384cd)
• tests: add server interaction helpers for model state management (a85f0a3)
• tests: add smoke tests for CLI commands against live Archi server (a85f0a3)
• tests: create fixture files for valid, invalid, and duplicate tempId BOMs (a85f0a3)
• tests: implement CLI test harness for executing commands and parsing responses (a85f0a3)
• undoableCommands: implement operation-aligned chunking and post-execution result refresh (aa50f2e)

Bug Fixes

• api: add retry logic for HTTP 429 responses during API requests (e978938)
• poll: add retry logic for HTTP 429 responses during polling (e978938)

Documentation

• add batch execution and rollback recommendations (aa50f2e)
• update batch-rollback-recommendations to reflect completion of all recommendations (e978938)

Maintenance

• add ArchiMate model for server (df97ca4)
• remove outdated model and integration documentation from README (8c666a4)
• serverConfig: lower maxSubCommandsPerBatch to 50 for improved stability (aa50f2e)
• tests: configure Vitest for testing environment and timeout settings (a85f0a3)

Tests

• update tests to reflect changes in batch apply command and validation logic (e978938)

1.4.0 (2026-02-09)

Features

• api: add relationshipLimit to model query and return relationship samples (a37ec51)
• api: implement createView and deleteView operations in OpenAPI schema (a37ec51)
• api: implement operation listing functionality in operation queue (5874646)
• api: update OpenAPI schema to include nestInView operation (712b1e4)
• archicli: add command for listing recent operations with options for limit and status (5874646)
• args: add argument validation utilities for strict integer and bounded float parsing (e766c2a)
• batch: add parseExistingIdFromError function and allow-empty option for batch apply command (0a9017b)
• batch: enhance batch apply command with new reference ID fields and error handling (9bbe4d6)
• batch: enhance error handling and reporting for batch apply operations (379b5e3)
• bom.schema: allow tempId in createFolder operations within BOM schema (0a9017b)
• bom: implement BOM loading with diagnostics and duplicate temp ID detection (e766c2a)
• cli: add Archi Command Line Interface documentation (2102d08)
• cli: implement view delete command for deleting views by ID (a37ec51)
• commander: introduce utility to identify Commander errors (e766c2a)
• config: add wide option for disabling column truncation in output (0a9017b)
• enhance CLI commands with improved error handling and validation (9623f9e)
• enhance command descriptions and validation for batch operations (94518d7)
• enhance command descriptions and validation for view creation and batch operations (d8ac38f)
• enhance command validation and error handling for batch operations and view creation (dce0d88)
• folder: introduce folder management commands for organizing model elements (f846ba9)
• health: enhance health command output formatting for text mode (0a9017b)
• ids: add command for looking up tempIds in .ids.json files (f846ba9)
• model: add complete ArchiMate documentation model with relationships and views (c126aa2)
• model: add save command to persist model state (f846ba9)
• model: include show-views option in model query command (0a9017b)
• model: remove deprecated relationship and view definitions (8b462f7)
• model: update view creation to support viewpoint assignment (8b462f7)
• openapi: update API schema to include structured error details for operations (379b5e3)
• operations: add endpoint to list recent async operations with filtering options (5874646)
• output: adjust table formatting based on wide mode configuration (0a9017b)
• settings: add new Bash commands for archicli view and ls (cc8da3e)
• tempIds: implement temp ID resolution and substitution logic (e766c2a)
• tests: add integration tests for /ops/list endpoint and its filtering capabilities (5874646)
• tests: add unit tests for nestInView and addToView with parentVisualId (712b1e4)
• types: add ArchiMate types constants for validation (a37ec51)
• update version to 1.3.0 and improve CLI functionality (e11d12c)
• validation: add validation for nestInView operation and parentVisualId in addToView (712b1e4)
• verify: add semantic validation checks for BOM and improve duplicate tempId detection (379b5e3)
• view: add support for nesting visual objects with parentVisualId and nestInView operations (712b1e4)
• view: add viewpoint normalization and validation in server endpoints (e766c2a)
• view: enhance view creation with viewpoint validation and error handling (e766c2a)
• view: implement layout command for auto-arranging view elements (f846ba9)
• view: improve view export command with scale and margin validation (e766c2a)
• view: update view export command to handle text output format (0a9017b)
• workspaces: add workspaces configuration for archicli (d72220d)

Bug Fixes

• api: handle relationshipLimit in model query response (a37ec51)
• batch: correct tempId mapping logic for viewId and improve note/group ID handling (3e66459)
• logging: improve resilience of logging queue during UI inactivity (f846ba9)
• monitor: implement heartbeat mechanism to prevent ghost window issue (f846ba9)
• openapi-ts: correct plugin name and adjust postProcess configuration (d869d6e)
• poll: extend OperationErrorDetails interface for better error context (379b5e3)
• verify: enhance validation for addConnectionToView direction consistency (f846ba9)
• viewEndpoints: include parentId in element data for nested visual objects (712b1e4)
• viewEndpoints: include viewpoint in create view operation (8b462f7)
• view: ensure viewpoint is correctly retrieved in view get command (e766c2a)
• view: handle errors consistently in view list command (e766c2a)

Documentation

• add bug fix documentation for ghost window issue in monitor UI (f846ba9)
• add initial report for archicli v0.1.0 testing (a37ec51)
• cli: add TypeScript CLI instructions and BOM file format details (1091f09)
• pattern: update prompts to include nesting instructions for compound elements (712b1e4)
• README: document nesting behavior for compound elements in addToView (712b1e4)
• update output behavior in help text for clarity (e766c2a)
• workflow: clarify usage of parentVisualId and nestInView in workflow templates (712b1e4)

Maintenance

• remove obsolete Archi CLI documentation and schema files (4714105)
• remove outdated suggestion documents from the repository (b28566d)

Code Refactoring

• undoableCommands: enhance addToView and nestInView command handling (712b1e4)

Tests

• add unit tests for parseExistingIdFromError and BOM schema validation (0a9017b)
• api: add tests for relationshipLimit in model query (a37ec51)
• archicli: add unit tests for batch apply --save-ids path resolution (5874646)
• remediation: add unit tests for archicli remediation helpers (a37ec51)

[Unreleased]

CLI

• add strict idFiles handling for verify --semantic and batch apply with --allow-incomplete-idfiles override
• add model search --strict-types, duplicate --type rejection, and client-side --name regex validation
• add batch apply --skip-existing for duplicate-create idempotent reruns
• add view delete <id> command
• add model query --show-relationships --relationship-limit <n>
• add global --output yaml and --quiet flags
• add view export --output-file alias
• standardize split flag naming to --chunk-size with deprecated --size alias
• improve view get text output readability and completion support for model search --type values

Server/API

• extend POST /model/query to accept relationshipLimit and return sampled relationships
• align OpenAPI ChangeOperation mappings with createView and deleteView

Schemas/Docs

• add deleteView support to BOM schema
• update CLI and README help text around sync/async behavior, polling caveats, and new flags

1.3.0 (2026-02-07)

Features

• add archimate modeling capabilities and auditing prompts (c35a625)
• archimate modeling skills (41d3637)
• tests: add manual verification for duplicate detection feature (c09097a)

1.2.0 (2026-02-07)

Features

• add release automation and commit linting (609f936)
• make standalone deleteElement use undoable manual cascade (a1690cf)

1.1.0 - 2026-02-07

Features

• Production-ready HTTP REST API server for Archi
• Comprehensive model query and modification endpoints
• Dynamic view creation and layout (Dagre algorithm)
• Full undo/redo support for all operations
• Real-time monitoring UI with operation logs
• Asynchronous operation queue with status tracking
• Script execution endpoint for custom jArchi code

Security

• Rate limiting (200 requests/minute per IP)
• Request size limits (1MB max body size)
• Operation timeouts (60 second default)
• Input validation and type checking
• CORS origin controls
• Localhost-only binding by default

API Endpoints

• /health - Server health and diagnostics
• /model/query - Query elements and relationships
• /model/apply - Batch create/update/delete operations
• /model/search - Search by name, type, or properties
• /views - List, create, update, delete views
• /views/{id}/layout - Apply automatic layout
• /views/{id}/export - Export views as images
• /scripts/run - Execute custom scripts
• /ops/status - Operation status tracking
• /shutdown - Graceful server shutdown

Documentation

• Complete OpenAPI specification
• Comprehensive README with examples
• Development documentation in context/ folder
• Python and Node.js client examples

Infrastructure

• Modular architecture with endpoint separation
• Efficient model snapshot caching
• Background operation processing
• Thread-safe queue management
• Graceful error handling and recovery