steve
e973b2ce20
- Implemented `pcli project export` command to export project hierarchy as JSON. - Added `pcli project import` command to import project data from JSON. - Created user client to fetch user details for comment attribution. - Introduced new data structures for export and import processes. - Ensured name-based references in exports and handled conflicts during imports. - Added versioning and progress reporting for import operations. - Updated documentation and specifications for new features.
4.6 KiB
project-export Spec
Purpose
Enable users to export a complete Planka project hierarchy (boards, lists, cards, labels, tasks, comments) to a portable JSON format for backup, migration, or documentation purposes.
Requirements
Requirement: Export project hierarchy to JSON
The system SHALL export a complete project hierarchy as a JSON object to stdout. The export SHALL include: project metadata, boards, lists, labels, cards (with list and label name references), task lists, tasks, and comments.
Scenario: Export entire project
- WHEN user runs
pcli project export <project-id-or-name> - THEN the system outputs a JSON object to stdout containing the project and all its boards with their full hierarchy
Scenario: Export with board filter
- WHEN user runs
pcli project export <project-id-or-name> --board <board-name-or-id> - THEN the system outputs a JSON object containing only the specified board (and its full hierarchy) under the project
Scenario: Board filter does not match
- WHEN user runs
pcli project export <project> --board <nonexistent> - THEN the system exits with an error indicating the board was not found
Requirement: Export format uses version envelope
The export JSON SHALL contain a version field (integer, currently 1), an exportedAt timestamp (ISO 8601), and a project object.
Scenario: Export envelope structure
- WHEN an export is generated
- THEN the root JSON object contains exactly
version,exportedAt, andprojectkeys - THEN
versionis1 - THEN
exportedAtis a valid ISO 8601 timestamp
Requirement: Export uses name-based references
The export SHALL use names instead of IDs for all cross-references. Cards SHALL reference their list by listName and their labels by labelNames (array of label name strings). No Planka IDs SHALL appear in the export.
Scenario: Card references list by name
- WHEN a card belongs to a list named "In Progress"
- THEN the exported card has
"listName": "In Progress"instead of a list ID
Scenario: Card references labels by name
- WHEN a card has labels "Bug" and "Urgent"
- THEN the exported card has
"labelNames": ["Bug", "Urgent"]
Requirement: Export preserves ordering
The export SHALL include position fields for boards, lists, labels, and cards to maintain their display ordering on import.
Scenario: List ordering preserved
- WHEN a board has lists "Todo" (position 1), "Doing" (position 2), "Done" (position 3)
- THEN the exported lists include their position values
Requirement: Export includes comment attribution
Each exported comment SHALL have its text prefixed with (Original comment by <username>)\n where <username> is resolved from the comment's userId. If the userId cannot be resolved, the prefix SHALL use unknown user.
Scenario: Comment with known author
- WHEN a comment was authored by user "jsmith"
- THEN the exported comment text starts with
(Original comment by jsmith)\n
Scenario: Comment with unresolvable author
- WHEN a comment's userId does not match any known user
- THEN the exported comment text starts with
(Original comment by unknown user)\n
Requirement: Export excludes user-specific data
The export SHALL NOT include cardMemberships, creatorUserId, or userId fields. Only textual comment attribution (as a text prefix) SHALL preserve user information.
Scenario: Card memberships excluded
- WHEN a card has members assigned
- THEN the exported card does not contain membership data
Requirement: Export includes task lists and tasks
The export SHALL include task lists and their tasks for each card. Each task list SHALL contain its tasks inline. Tasks SHALL include name and isCompleted fields.
Scenario: Card with task lists
- WHEN a card has a task list "Checklist" with tasks "Item 1" (complete) and "Item 2" (incomplete)
- THEN the exported card includes the task list with both tasks and their completion status
Requirement: Project identified by name or ID
The <project-id-or-name> argument SHALL accept either a Planka project ID or a project name. If a name is provided, the system SHALL look up the project by name. If multiple projects match the name, the system SHALL exit with an error.
Scenario: Project by name
- WHEN user provides a project name that matches exactly one project
- THEN the system exports that project
Scenario: Ambiguous project name
- WHEN user provides a project name that matches multiple projects
- THEN the system exits with an error listing the matches