You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/06/08 10:34:21 UTC
(causeway) 01/17: CAUSEWAY-4025: adds command export manager simplification proposal
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-4028
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit aec566684aa8126c2909397db1a8788d9af17336
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Jun 8 08:41:44 2026 +0100
CAUSEWAY-4025: adds command export manager simplification proposal
---
.../.openspec.yaml | 2 +
.../design.md | 49 +++++++++++++++++
.../proposal.md | 28 ++++++++++
.../command-export-command-reordering/spec.md | 61 +++++++++++++++++++++
.../specs/command-export-known-targets/spec.md | 56 +++++++++++++++++++
.../command-export-manager-command-list/spec.md | 64 ++++++++++++++++++++++
.../tasks.md | 28 ++++++++++
7 files changed, 288 insertions(+)
diff --git a/openspec/changes/simplify-command-export-manager-commands/.openspec.yaml b/openspec/changes/simplify-command-export-manager-commands/.openspec.yaml
new file mode 100644
index 00000000000..e8d4ccfe905
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-08
diff --git a/openspec/changes/simplify-command-export-manager-commands/design.md b/openspec/changes/simplify-command-export-manager-commands/design.md
new file mode 100644
index 00000000000..378e9f34eab
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/design.md
@@ -0,0 +1,49 @@
+## Context
+
+`CommandExportManager` currently stores baseline, page limit, and mode in its view-model memento.
+The mode toggles between an export view backed by `notYetExported` and an unexport view backed by `exported`.
+Exporting selected commands still updates their replay state to `EXPORTED`, and existing per-command actions can move commands or make them exportable again.
+The newer workflow needs users to arrange commands and preserve dotted-path reachability across the full baseline-bounded sequence, so hiding exported commands behind a separate mode makes the page less useful.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide one export-manager collection named `commands` for all foreground commands at or after the baseline.
+- Remove mode and toggle behavior from the export manager UI and memento.
+- Keep export marking by setting exported command log entries to replay state `EXPORTED` after successful YAML creation.
+- Show replay state in the unified command list so users can distinguish exported and not-yet-exported entries without switching modes.
+- Update actions and tests to use the unified collection as their choice source and association target.
+
+**Non-Goals:**
+- Do not preserve backward compatibility for old view-model mementos, collection names, or UI toggle behavior.
+- Do not change command YAML structure or command replay import behavior.
+- Do not change the existing dotted-path validation rules except to evaluate selections in the unified command-list workflow.
+
+## Decisions
+
+- Replace `Mode`, `withMode`, `getNotYetExported`, `getExported`, and their hide/support methods with a single `getCommands` collection.
+ Alternative considered: keep the mode but make it default to all commands.
+ That preserves obsolete concepts and continues to split the user workflow, so the mode should be removed.
+
+- Persist only baseline and limit in the export-manager memento.
+ Alternative considered: keep a third memento segment and ignore it.
+ The request explicitly says not to worry about backward compatibility, so the simpler memento shape is acceptable.
+
+- Use repository queries that return all foreground commands since or before the baseline without filtering on replay state.
+ Alternative considered: combine exported and not-yet-exported query results in memory.
+ A single repository-level query avoids merge-order mistakes and better reflects the collection semantics.
+
+- Keep export actions from re-exporting commands only if explicitly required by validation or selection rules.
+ Alternative considered: filter exported commands out of the selected entries as a safety measure.
+ That would contradict the unified list, so the action should operate on the selected commands from `commands` and then mark them `EXPORTED` after successful export.
+
+- Rename layout and column-order fallback resources to target `commands`.
+ Alternative considered: leave old resources in place until manually cleaned later.
+ The UI contract changes now, so stale resources should be removed or replaced in the same change.
+
+## Risks / Trade-offs
+
+- Users may accidentally re-export commands whose replay state is already `EXPORTED` → The list displays replay state and the generated YAML still reflects the explicit selection.
+- Removing memento compatibility can reset bookmarked export-manager URLs → This is accepted because backward compatibility is out of scope.
+- Repository query changes can affect pagination boundaries → Add tests for next and previous page behavior over mixed replay states.
+- Dotted-path validation can become confusing if users select only part of the visible sequence → Keep validation scoped to the selected export sequence while target choices and move operations use the unified baseline-bounded command set.
diff --git a/openspec/changes/simplify-command-export-manager-commands/proposal.md b/openspec/changes/simplify-command-export-manager-commands/proposal.md
new file mode 100644
index 00000000000..7e3ee0586f1
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+The command export manager was designed around batch export, where exported commands are removed from the default working list by changing replay state from `UNDEFINED` to `EXPORTED`.
+That model no longer fits the more fluid workflow needed to keep dotted paths valid and move commands into replayable order.
+
+## What Changes
+
+- Replace the export manager's mode-based command collections with a single `commands` collection containing all commands at or after the baseline.
+- Remove the UI mode and toggle action that switch between not-yet-exported and exported commands.
+- Continue updating replay state from `UNDEFINED` to `EXPORTED` when commands are exported, so users can see which commands have already been exported.
+- Include replay state as a visible property in the unified `commands` list.
+- **BREAKING**: Remove the old `notYetExported` and `exported` collections and their mode-driven navigation semantics without preserving backward compatibility.
+
+## Capabilities
+
+### New Capabilities
+- `command-export-manager-command-list`: Defines the unified baseline-bounded command list, replay-state visibility, and removal of mode-based filtering.
+
+### Modified Capabilities
+- `command-export-command-reordering`: Align move-command selection and target choices with the unified baseline-bounded command list.
+- `command-export-known-targets`: Clarify that export validation evaluates selected commands within the unified baseline-bounded command list rather than a replay-state-filtered list.
+
+## Impact
+
+- Affects `CommandExportManager` and related mixins under `extensions/core/commandlog/applib`.
+- Affects fallback layout and column order resources for the export manager.
+- Affects tests that assert mode behavior, collection names, command filtering, move choices, export selection, and replay-state display.
+- No new dependencies are expected.
diff --git a/openspec/changes/simplify-command-export-manager-commands/specs/command-export-command-reordering/spec.md b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-command-reordering/spec.md
new file mode 100644
index 00000000000..eaec15b2e95
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-command-reordering/spec.md
@@ -0,0 +1,61 @@
+## MODIFIED Requirements
+
+### Requirement: Export manager moves selected commands after a target command
+When command-log recording support is `ENABLED`, the export manager SHALL provide an action to move one or more selected commands from the unified commands collection after a target command.
+When command-log recording support is `DISABLED`, the export manager MUST disable command movement.
+The action SHALL operate only on commands at or after the export manager baseline.
+The target command choices SHALL include commands at or after the export manager baseline from the unified commands collection.
+The target command choices MUST exclude every command selected for movement.
+The action MUST reject execution when no commands are selected.
+The action MUST reject execution when the target command is missing.
+The action MUST reject execution when the target command is one of the selected commands.
+The action MUST reject execution when any selected command or target command is outside the baseline-bounded command set.
+The action MUST NOT exclude a selected command or target command merely because its replay state is `EXPORTED`.
+
+#### Scenario: Target choices exclude selected commands
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** commands `A`, `B`, and `C` are in the unified commands collection after the baseline
+- **AND** commands `A` and `B` are selected for movement
+- **WHEN** the system provides target choices for the move action
+- **THEN** command `C` is offered as a target choice
+- **AND** commands `A` and `B` are not offered as target choices
+
+#### Scenario: Target choices include exported commands
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** command `A` has replay state `UNDEFINED`
+- **AND** command `B` has replay state `EXPORTED`
+- **AND** commands `A` and `B` are in the unified commands collection after the baseline
+- **AND** command `A` is selected for movement
+- **WHEN** the system provides target choices for the move action
+- **THEN** command `B` is offered as a target choice
+
+#### Scenario: Cannot move without a selection
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **WHEN** the user invokes the move action with no selected commands
+- **THEN** the system rejects the invocation
+- **AND** no command timestamps are changed
+
+#### Scenario: Cannot move after a selected command
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** command `A` is selected for movement
+- **WHEN** the user invokes the move action using command `A` as the target command
+- **THEN** the system rejects the invocation
+- **AND** no command timestamps are changed
+
+#### Scenario: Cannot move commands outside the baseline-bounded set
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** command `A` is before the baseline
+- **WHEN** a caller bypasses the UI and invokes the move action with command `A` selected
+- **THEN** the system rejects the invocation
+- **AND** no command timestamps are changed
+
+#### Scenario: Move action is disabled when recording support is disabled
+- **GIVEN** command-log recording support is `DISABLED`
+- **AND** an export manager baseline is set
+- **WHEN** the framework evaluates the move action
+- **THEN** the move action is disabled
diff --git a/openspec/changes/simplify-command-export-manager-commands/specs/command-export-known-targets/spec.md b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-known-targets/spec.md
new file mode 100644
index 00000000000..2cbfdcbc1b7
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-known-targets/spec.md
@@ -0,0 +1,56 @@
+## MODIFIED Requirements
+
+### Requirement: Export target knowledge follows baseline-bounded export order
+The export manager SHALL evaluate target knowledge using the same command ordering that command export uses for replayable sequences.
+The export manager SHALL use current command timestamps when evaluating baseline-bounded export order.
+The export manager SHALL derive the available export-order context from the unified commands collection rather than from a replay-state-filtered collection.
+When command timestamps have been changed by an export-manager command move action, the changed timestamps SHALL determine whether a command result is earlier or later for target and reference-parameter validation.
+A command result SHALL make a bookmark known only for selected commands that occur later in that ordering.
+A command result MUST NOT make the same bookmark known for an earlier selected command or for another selected command whose ordering is not after the result-producing command.
+A command before the export manager baseline MUST NOT make a target known for the selected export sequence.
+A command's replay state MUST NOT by itself make the command unavailable as an earlier result for export target knowledge when the command is at or after the baseline and participates in the selected export sequence.
+
+#### Scenario: Later result does not validate earlier selected target
+- **GIVEN** an export manager baseline is set
+- **AND** a selected action command targets bookmark `demoCustomer:1`
+- **AND** a later selected command in export order has result bookmark `demoCustomer:1`
+- **WHEN** the export manager validates the selected command sequence
+- **THEN** the system rejects the earlier selected command because the target was not known at that point in the export sequence
+
+#### Scenario: Earlier result validates later selected target
+- **GIVEN** an export manager baseline is set
+- **AND** a command with result bookmark `demoCustomer:1` appears earlier in export order and at or after the baseline
+- **WHEN** a selected later action command targets bookmark `demoCustomer:1`
+- **THEN** the export manager accepts the later command for export
+
+#### Scenario: Exported earlier result validates later selected target
+- **GIVEN** an export manager baseline is set
+- **AND** a selected command with replay state `EXPORTED` has result bookmark `demoCustomer:1`
+- **AND** that selected command appears earlier in export order and at or after the baseline
+- **WHEN** a selected later action command targets bookmark `demoCustomer:1`
+- **THEN** the export manager accepts the later command for export
+
+#### Scenario: Result before baseline does not validate selected target
+- **GIVEN** an export manager baseline is set
+- **AND** a command before the baseline has result bookmark `demoCustomer:1`
+- **WHEN** a selected later action command targets bookmark `demoCustomer:1`
+- **THEN** the export manager rejects the selected command unless another command at or after the baseline establishes `demoCustomer:1`
+
+#### Scenario: Moved finder result validates later selected target
+- **GIVEN** an export manager baseline is set
+- **AND** a selected action command targets bookmark `demoCustomer:1`
+- **AND** a selected finder command has result bookmark `demoCustomer:1`
+- **AND** the finder command originally occurs later than the action command
+- **WHEN** the user moves the finder command before the action command using the export manager move action
+- **AND** the export manager validates the selected command sequence
+- **THEN** the export manager accepts the action command target as known
+
+#### Scenario: Moved navigation result validates later selected reference parameter
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** a selected action command has reference parameter `customer` with bookmark `demoCustomer:1`
+- **AND** a selected navigation command has result bookmark `demoCustomer:1`
+- **AND** the navigation command originally occurs later than the action command
+- **WHEN** the user moves the navigation command before the action command using the export manager move action
+- **AND** the export manager validates the selected command sequence
+- **THEN** the export manager accepts the action command reference parameter as known
diff --git a/openspec/changes/simplify-command-export-manager-commands/specs/command-export-manager-command-list/spec.md b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-manager-command-list/spec.md
new file mode 100644
index 00000000000..4633d838251
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/specs/command-export-manager-command-list/spec.md
@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Export manager shows one baseline-bounded command collection
+The export manager SHALL expose a collection named `commands`.
+The `commands` collection SHALL contain foreground command log entries at or after the export manager baseline.
+The `commands` collection MUST include command log entries regardless of whether their replay state is `UNDEFINED`, `EXPORTED`, or another replay state.
+The `commands` collection SHALL be ordered by the command ordering used for command export and command movement.
+The export manager MUST NOT expose separate mode-filtered collections for not-yet-exported commands and exported commands.
+
+#### Scenario: Unified command list includes mixed replay states
+- **GIVEN** an export manager baseline is set
+- **AND** command `A` at or after the baseline has replay state `UNDEFINED`
+- **AND** command `B` at or after the baseline has replay state `EXPORTED`
+- **WHEN** the user views the export manager commands collection
+- **THEN** command `A` is included
+- **AND** command `B` is included
+
+#### Scenario: Commands before baseline are excluded
+- **GIVEN** an export manager baseline is set
+- **AND** command `A` is before the baseline
+- **AND** command `B` is at or after the baseline
+- **WHEN** the user views the export manager commands collection
+- **THEN** command `A` is not included
+- **AND** command `B` is included
+
+### Requirement: Export manager removes mode switching
+The export manager SHALL use a single command-list mode.
+The export manager MUST NOT expose a mode property that switches between exported and not-yet-exported commands.
+The export manager MUST NOT expose a toggle action for switching between exported and not-yet-exported command lists.
+The export manager view-model memento SHALL store the baseline and page limit needed for the unified command list.
+The export manager view-model memento MUST NOT store a command-list mode.
+
+#### Scenario: Export manager page has no toggle mode action
+- **WHEN** the user views the export manager
+- **THEN** there is no action to toggle between exported and not-yet-exported commands
+- **AND** the commands collection remains visible as the single command list
+
+#### Scenario: Memento stores only unified list state
+- **GIVEN** an export manager has a baseline and page limit
+- **WHEN** the export manager creates its view-model memento
+- **THEN** the memento contains the baseline
+- **AND** the memento contains the page limit
+- **AND** the memento does not contain a command-list mode
+
+### Requirement: Exported replay state remains visible and updated
+The export manager commands collection SHALL display each command's replay state.
+When selected commands are exported successfully, the export manager SHALL set those command log entries to replay state `EXPORTED`.
+A command whose replay state is `EXPORTED` MUST remain eligible to appear in the commands collection.
+Exporting selected commands MUST NOT remove those commands from the commands collection merely because their replay state changed.
+
+#### Scenario: Export updates replay state without removing command
+- **GIVEN** an export manager baseline is set
+- **AND** command `A` is in the commands collection with replay state `UNDEFINED`
+- **WHEN** the user exports command `A`
+- **THEN** command `A` has replay state `EXPORTED`
+- **AND** command `A` remains eligible for the commands collection
+
+#### Scenario: Replay state column distinguishes already exported commands
+- **GIVEN** an export manager baseline is set
+- **AND** command `A` in the commands collection has replay state `UNDEFINED`
+- **AND** command `B` in the commands collection has replay state `EXPORTED`
+- **WHEN** the user views the commands collection
+- **THEN** the replay state for command `A` is visible
+- **AND** the replay state for command `B` is visible
diff --git a/openspec/changes/simplify-command-export-manager-commands/tasks.md b/openspec/changes/simplify-command-export-manager-commands/tasks.md
new file mode 100644
index 00000000000..65da56504c7
--- /dev/null
+++ b/openspec/changes/simplify-command-export-manager-commands/tasks.md
@@ -0,0 +1,28 @@
+## 1. Export Manager State and Collections
+
+- [ ] 1.1 Remove `CommandExportManager.Mode`, `mode`, `withMode`, and mode parsing/serialization from `CommandExportManager` state.
+- [ ] 1.2 Replace `getNotYetExported` and `getExported` with a single `getCommands` collection that returns all foreground commands at or after the baseline regardless of replay state.
+- [ ] 1.3 Replace previous-page support with unified command paging that is not replay-state filtered.
+- [ ] 1.4 Remove `CommandExportManager_toggleMode` and its references from layouts, tests, and generated metadata expectations.
+
+## 2. Actions and UI Metadata
+
+- [ ] 2.1 Update `CommandExportManager_exportSelected` to associate with and choose from `commands`.
+- [ ] 2.2 Update export selection handling so selected commands from `commands` are exported and then marked `EXPORTED` without disappearing because of replay state.
+- [ ] 2.3 Update `CommandExportManager_moveCommands` to associate with and choose from `commands`, including commands whose replay state is `EXPORTED`.
+- [ ] 2.4 Rename or replace fallback column-order resources so the unified `commands` collection displays replay state.
+- [ ] 2.5 Update fallback layout resources to remove mode/toggle UI and show the unified `commands` collection.
+
+## 3. Repository Queries and Validation
+
+- [ ] 3.1 Add or reuse repository methods for foreground commands since and before the baseline without replay-state filtering.
+- [ ] 3.2 Ensure move-command validation rejects only commands outside the baseline-bounded command set, not commands with replay state `EXPORTED`.
+- [ ] 3.3 Ensure known-target validation continues to use selected command order and can use selected earlier result commands regardless of replay state.
+
+## 4. Tests and Verification
+
+- [ ] 4.1 Update export-manager state tests for baseline-and-limit mementos with no mode.
+- [ ] 4.2 Update collection tests to assert `commands` includes mixed `UNDEFINED` and `EXPORTED` replay states and excludes commands before the baseline.
+- [ ] 4.3 Update export-selected tests for the `commands` association and replay-state update behavior.
+- [ ] 4.4 Update move-command tests for unified command choices and exported target commands.
+- [ ] 4.5 Run the commandlog applib test suite or the nearest affected Maven module tests.