npm - @ngocsangairvds/vsaf - Versions diffs - 4.1.7 → 4.1.9 - Mend

@ngocsangairvds/vsaf 4.1.7 → 4.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1063) hide show

package/skills/vds-skill/vds-scripts/jira_orchestrator/README.md DELETED Viewed

@@ -1,864 +0,0 @@
-# VDS JIRA Orchestrator
-Python toolkit for JIRA operations using the `atlassian-python-api` SDK. Provides a unified CLI interface for issue
-tracking, project management, and JIRA automation.
-## Quick Start
-```bash
-cd WHO-project/vds-scripts
-# Optional: sync all orchestrators once
-./scripts/bootstrap_uv.sh
-# Package-specific sync & tests
-uv sync --project jira_orchestrator --extra dev
-uv run --project jira_orchestrator pytest
-```
-Run the CLI directly (uv automatically loads the project environment once it has been synced at least once):
-```bash
-# Using uv run (console script)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira --help
-# Using the unified VDS CLI
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env load
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --limit 20
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --limit 20 --json-only
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue NTTC-123
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira projects --limit 50
-```
-**Agent-friendly output**
-- When using `vds-cli`, put Typer flags after `--` (e.g. `vds-cli jira -- --json-only projects`).
-- `--json-only` emits clean JSON only (no reports/markdown, logs suppressed).
-- `--no-reports` keeps normal console output but avoids writing report files.
-## Available Commands
-### Read Operations
-- **`projects`** - List all JIRA projects
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira projects --limit 50
-  # Optional filters:
-  #   --search "keyword"   (matches name or key, case-insensitive)
-  #   --limit 10           (applied after filtering)
-  ```
-- **`search`** - Search issues using JQL
-  ```bash
-  # Basic search
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC AND status = Open" --limit 50
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "assignee = currentUser()" --fields "summary,status,priority"
-  # Advanced search with pagination
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --advanced --start 10 --limit 25
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --start 0 --limit 50 --fields "summary,status"
-  ```
-  > **Cloud requirement**: Atlassian's May 2025 change requires `enhanced_jql` for all Cloud tenants. The CLI detects
-  > `*.atlassian.net` base URLs and automatically routes searches through the enhanced endpoint (see announcement:
-  > <https://support.atlassian.com/cloud-migration/docs/changes-to-search-api-july-2024/>).\
-  > **Advanced search**: Use `--advanced` flag or `--start` parameter to enable pagination support. The `--start`
-  > parameter automatically enables advanced search mode.
-- **`search-by-filter`** - Search issues using a saved filter
-  ```bash
-  # Search using filter ID
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search-by-filter 10000 --limit 50
-  # Search with pagination
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search-by-filter 10000 --start 20 --limit 25 --fields "summary,status,priority"
-  ```
-  > **Note**: Uses the JQL from the saved filter to perform the search. Supports pagination and field selection.
-- **`issue`** - Get issue details
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue NTTC-123
-  ```
-- **`bulk-update`** - Bulk update multiple issues
-  ```bash
-  # Bulk update with JSON fields
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira bulk-update \
-    --issue-keys "NTTC-1,NTTC-2,NTTC-3" \
-    --fields '{"summary":"Updated summary"}' \
-    --yes
-  # Bulk update with fields file
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira bulk-update \
-    --issue-keys "NTTC-1,NTTC-2" \
-    --fields-file ./fields.json \
-    --yes
-  # Bulk update all fields (default)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira bulk-update \
-    --issue-keys "NTTC-1,NTTC-2" \
-    --yes
-  ```
-  > **Notes**:
-  >
-  > - Requires `--yes` flag for confirmation
-  > - `--fields` accepts JSON string or `"*all"` (default) for all fields
-  > - `--fields-file` accepts a JSON file containing field updates
-  > - Multiple issue keys should be comma-separated
-- **`field-append`** - Append value to issue field (for multi-select fields)
-  ```bash
-  # Append value with JSON string
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira field-append \
-    --issue-key NTTC-123 \
-    --field customfield_10000 \
-    --value '{"name":"value"}' \
-    --yes
-  # Append value with file
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira field-append \
-    --issue-key NTTC-123 \
-    --field customfield_10000 \
-    --value-file ./value.json \
-    --yes
-  # Append without notifying users
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira field-append \
-    --issue-key NTTC-123 \
-    --field customfield_10000 \
-    --value '{"name":"value"}' \
-    --no-notify \
-    --yes
-  ```
-  > **Notes**:
-  >
-  > - Requires `--yes` flag for confirmation
-  > - `--value` must be a JSON object (dict)
-  > - `--value-file` accepts a JSON file containing the value object
-  > - Use `--no-notify` to prevent user notifications
-  > - Primarily used for multi-select custom fields
-- **`issue-archive`** - Archive an issue
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-archive --issue-key NTTC-123 --yes
-  ```
-  > **Warning**: Archiving an issue removes it from normal views. Use `issue-restore` to restore archived issues.
-- **`issue-restore`** - Restore an archived issue
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-restore --issue-key NTTC-123 --yes
-  ```
-  > **Notes**:
-  >
-  > - Requires `--yes` flag for confirmation
-  > - Restores previously archived issues back to normal state
-- **`property`** - Manage JIRA application properties
-  ```bash
-  # Get property by key
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira property get --key "jira.lf.date.dmy"
-  # Get property with filters
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira property get \
-    --key "jira.lf.*" \
-    --permission-level SYSTEM \
-    --key-filter "jira.lf.*"
-  # Set property
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira property set \
-    --property-id "jira.lf.date.dmy" \
-    --value "true" \
-    --yes
-  ```
-  > **Notes**:
-  >
-  > - `get` action supports optional `--key`, `--permission-level`, and `--key-filter` parameters
-  > - `set` action requires `--property-id`, `--value`, and `--yes` flag
-- **`settings`** - Manage JIRA settings
-  ```bash
-  # Get advanced settings
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira settings advanced
-  ```
-  > Returns advanced JIRA configuration settings.
-- **`createmeta`** - Get create metadata for issue creation
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira createmeta --project NTTC --issuetype Task
-  ```
-- **`custom-fields`** - List custom fields
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira custom-fields --search "Story Points" --limit 10
-  ```
-- **`board`** - Agile board operations
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board list --project NTTC --limit 10
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board get --board-id 1
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board create --name "Sprint Board" --type scrum --filter-id 100 --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board issues --board-id 1
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board properties --board-id 1
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira board velocity --board-id 1
-  ```
-- **`epic`** - Epic operations
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira epic issues --epic-key NTTC-100
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira epic list --board-id 1 --limit 20
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira epic issues-for-epic --board-id 1 --epic-id 100
-  ```
-- **`sprint`** - Sprint operations
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint list --board-id 1 --limit 10
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint issues --board-id 1 --state active
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint versions --board-id 1
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint create --name "Sprint 1" --board-id 1 --start-date "2025-01-01" --end-date "2025-01-14" --goal "Complete features" --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint rename --sprint-id 100 --name "Updated Sprint" --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira sprint add-issues --sprint-id 100 --issues "NTTC-123,NTTC-124" --yes
-  ```
-- **`reindex`** - Reindex operations
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira reindex status
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira reindex start --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira reindex with-type BACKGROUND --yes
-  ```
-- **`worklog`** - Worklog operations (time tracking)
-  ```bash
-  # Get worklogs for an issue
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira worklog get --issue-key NTTC-123
-  # Add worklog entry
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira worklog add \
-    --issue-key NTTC-123 \
-    --time-spent "2h 30m" \
-    --comment "Implemented feature X" \
-    --started "2025-11-12T10:00:00Z" \
-    --yes
-  # Add worklog with time in seconds
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira worklog add \
-    --issue-key NTTC-123 \
-    --time-sec 7200 \
-    --comment "Code review" \
-    --yes
-  # Get updated worklogs since timestamp
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira worklog updated --since "2025-11-12 10:00:00"
-  # Get deleted worklogs since timestamp
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira worklog deleted --since "2025-11-12 10:00:00"
-  ```
-- **`transitions`** - Get available transitions for an issue
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira transitions NTTC-123
-  ```
-- **`changelog`** - Get issue change history
-  ```bash
-  # Get complete changelog
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira changelog get NTTC-123
-  # Get changelog with pagination
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira changelog get NTTC-123 --start 0 --limit 50
-  # Get status change history only
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira changelog status NTTC-123
-  ```
-- **`dashboard`** - Dashboard operations
-  ```bash
-  # Get dashboard by ID
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira dashboard get --dashboard-id 10000
-  # List dashboards
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira dashboard list
-  # List dashboards with filter and pagination
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira dashboard list --filter "project" --start 0 --limit 50
-  ```
-- **`filter`** - Filter management operations
-  ```bash
-  # List all filters
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter list
-  # List filters by owner
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter list --owner username
-  # Get filter by ID
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter get --filter-id 10000
-  # Create a new filter
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter create \
-    --name "My Filter" \
-    --jql "project = NTTC AND status = Open" \
-    --description "Open issues in NTTC project" \
-    --favourite \
-    --yes
-  # Update filter (name, JQL, description, or favourite status)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter update \
-    --filter-id 10000 \
-    --name "Updated Filter Name" \
-    --yes
-  # Delete filter
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira filter delete --filter-id 10000 --yes
-  ```
-  > **Notes**:
-  >
-  > - Write operations (create, update, delete) require `--yes` flag for confirmation
-  > - `update` requires at least one of: `--name`, `--jql`, `--description`, or `--favourite`
-  > - If `--jql` is not provided in `update`, the existing JQL is preserved
-- **`link-type`** - Issue link type operations
-  ```bash
-  # List all issue link types
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type list
-  # Get specific link type by ID
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type get --link-type-id 10000
-  # Create new link type
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type create \
-    --name "Tests" \
-    --inward "is tested by" \
-    --outward "tests" \
-    --yes
-  # Create link type from JSON file
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type create \
-    --data-file link_type.json \
-    --yes
-  # Update link type
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type update \
-    --link-type-id 10000 \
-    --name "Tests Updated" \
-    --inward "is tested by" \
-    --outward "tests" \
-    --yes
-  # Delete link type
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira link-type delete --link-type-id 10000 --yes
-  ```
-- **`remote-link`** - Issue remote link operations
-  ```bash
-  # List remote links for an issue
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira remote-link list --issue-key NTTC-123
-  # Create a remote link (with confirmation)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira remote-link create \
-    --issue-key NTTC-123 \
-    --url https://status.example.com/NTTC-123 \
-    --title "Status Page" \
-    --relationship "is documented by" \
-    --yes
-  # Update an existing remote link
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira remote-link update \
-    --issue-key NTTC-123 \
-    --remote-link-id 10 \
-    --url https://status.example.com/NTTC-123?updated=true \
-    --yes
-  # Delete a remote link
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira remote-link delete --issue-key NTTC-123 --remote-link-id 10 --yes
-  ```
-- **`issue-property`** - Issue property operations
-  ```bash
-  # List property keys for an issue
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-property list --issue-key NTTC-123
-  # Get a specific property
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-property get --issue-key NTTC-123 --property-key deploy.info
-  # Set a property using inline JSON (requires confirmation)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-property set \
-    --issue-key NTTC-123 \
-    --property-key deploy.info \
-    --value '{"env": "prod", "version": "1.2.3"}' \
-    --yes
-  # Set a property from JSON file
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-property set \
-    --issue-key NTTC-123 \
-    --property-key deploy.info \
-    --data-file deploy_info.json \
-    --yes
-  # Delete a property
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-property delete --issue-key NTTC-123 --property-key deploy.info --yes
-  ```
-- **`watcher`** - Issue watcher operations
-  ```bash
-  # List watchers
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira watcher list --issue-key NTTC-123
-  # Add watcher (username/accountId) with confirmation
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira watcher add --issue-key NTTC-123 --account user@example.com --yes
-  # Remove watcher
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira watcher remove --issue-key NTTC-123 --account user@example.com --yes
-  ```
-- **`component`** - Project component operations
-  ```bash
-  # Get a component
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira component get --component-id 10000
-  # Create a component (requires confirmation)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira component create \
-    --project-key NTTC \
-    --name "Payments" \
-    --description "Handles payment flows" \
-    --yes
-  # Update a component
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira component update \
-    --component-id 10000 \
-    --name "Payments Core" \
-    --yes
-  # Delete a component
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira component delete --component-id 10000 --yes
-  ```
-- **`user`** - User management operations
-  ```bash
-  # Search for users (Cloud: email/displayName, DC: username)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira user search --query "test@example.com"
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira user search --query "John Doe" --start 0 --limit 20
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira user search --query "test" --include-inactive
-  # Get user groups (Cloud only - requires account ID)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira user groups --account-id "5d5f5e5d5e5d5e5d5e5d5e5d"
-  # Deactivate a user (Jira 8.3.0+, requires confirmation)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira user deactivate --username "testuser" --yes
-  ```
-  > **Cloud/DC Differences**:
-  >
-  > - `user search`: In Cloud, searches by email/displayName/accountId. In DC, searches by username.
-  > - `user groups`: **Cloud only** - requires account ID (not username). Returns error on Server/DC.
-  > - `user deactivate`: Requires Jira 8.3.0+ and `--yes` flag for confirmation.
-- **`version`** - Project version management operations
-  ```bash
-  # List project versions with pagination and filtering
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version list --project-key NTTC
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version list --project-key NTTC --start 0 --limit 20
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version list --project-key NTTC --order-by name --query "1.0" --status released
-  # Create a new version (requires confirmation)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version create \
-    --project-key NTTC \
-    --project-id 10000 \
-    --name "1.0.0" \
-    --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version create \
-    --project-key NTTC \
-    --project-id 10000 \
-    --name "1.0.0" \
-    --archived \
-    --released \
-    --yes
-  # Update a version (requires confirmation and at least one field)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version update \
-    --version-id 10000 \
-    --name "1.0.1" \
-    --yes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira version update \
-    --version-id 10000 \
-    --description "Updated description" \
-    --archived \
-    --start-date "2025-01-01" \
-    --release-date "2025-01-31" \
-    --yes
-  ```
-  > **Notes**:
-  >
-  > - `version list`: Supports pagination (`--start`, `--limit`), sorting (`--order-by`: `sequence`, `name`,
-  >   `startDate`, `releaseDate`), and filtering (`--query`, `--status`).
-  > - `version create`: Requires `--project-key`, `--project-id`, `--name`, and `--yes` flag. Use `--archived` and
-  >   `--released` flags to set version state.
-  > - `version update`: Requires `--version-id`, `--yes` flag, and at least one update field (`--name`, `--description`,
-  >   `--archived`, `--released`, `--start-date`, `--release-date`).
-- **`security-scheme`** - Issue security scheme operations
-  ```bash
-  # List all security schemes
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira security-scheme list
-  # Get specific security scheme by ID
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira security-scheme get --scheme-id 10000
-  # Get security scheme with only levels
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira security-scheme get --scheme-id 10000 --only-levels
-  ```
-- **`permissions`** - Permission operations
-  ```bash
-  # Get all permission types
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permissions all
-  # Check permissions (global)
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permissions check --permissions "ADMINISTER_PROJECTS,BROWSE_PROJECTS"
-  # Check permissions in project context
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permissions check \
-    --permissions "ADMINISTER_PROJECTS" \
-    --project-key NTTC
-  # Check permissions in issue context
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permissions check \
-    --permissions "EDIT_ISSUES" \
-    --issue-key NTTC-123
-  ```
-- **`permission-scheme`** - Get project permission scheme
-  ```bash
-  # Get project permission scheme
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permission-scheme NTTC
-  # Get with expanded fields
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira permission-scheme NTTC --expand "permissions,user,group"
-  ```
-- **`issue-security-scheme`** - Get project issue security scheme
-  ```bash
-  # Get project issue security scheme
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-security-scheme NTTC
-  # Get with only levels
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue-security-scheme NTTC --only-levels
-  ```
-### Write Operations
-- **`create`** - Create a new issue
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira create \
-    --project NTTC \
-    --issuetype Task \
-    --summary "Implement feature X" \
-    --description "Detailed description here" \
-    --assignee username \
-    --labels "backend,high-priority" \
-    --set customfield_12345=10001 \
-    --yes
-  ```
-- **`update`** - Update issue fields
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira update NTTC-123 \
-    --set summary="Updated summary" \
-    --add-label "urgent" \
-    --remove-label "low-priority" \
-    --yes
-  ```
-- **`comment`** - Add comment to issue
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira comment NTTC-123 \
-    --message "This is a comment" \
-    --yes
-  ```
-- **`transition`** - Transition issue status
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira transition NTTC-123 \
-    --to "In Progress" \
-    --admin \
-    --yes
-  ```
-- **`delete`** - Delete an issue (requires --yes and --force)
-  ```bash
-  ./scripts/worktree_uv.sh run --project vds_cli vds-cli jira delete NTTC-123 --yes --force
-  ```
-## Working with Custom Fields
-### Discovering Fields
-When creating issues, you may need to provide mandatory custom fields. Use `discover-fields` to find the correct IDs and allowed values for your project and issue type. By default, it returns custom fields only; use `--include-system` to include system fields.
-```bash
-# List custom fields for a project/issuetype (default)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira discover-fields --project NTTC --issuetype Task
-# Include system fields
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira discover-fields --project NTTC --issuetype Task --include-system
-# Filter for a specific field name or ID
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira discover-fields --project NTTC --issuetype Task --field "Vai trò"
-# Fallback to editmeta using an existing issue key
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira discover-fields --project NTTC --issuetype Task --issue-key NTTC-123
-```
-**Output Example:**
-```json
-{
-  "project": "NTTC",
-  "issueType": "Task",
-  "count": 1,
-  "duration_ms": 1035,
-  "fields": [
-    {
-      "id": "customfield_15200",
-      "name": "Vai trò - Công đoạn",
-      "required": true,
-      "type": "option-with-child",
-      "is_custom": true,
-      "allowedValues": [
-        {"id": "14901", "value": "SA"},
-        {"id": "14902", "value": "BA"}
-      ]
-    }
-  ]
-}
-```
-`duration_ms` captures how long field discovery took and is used for performance warnings.
-### Providing Complex Values
-Some custom fields (like dropdowns, cascading selects) require a JSON object structure rather than a simple string. The `--set` parameter supports JSON values.
-**Syntax:** `--set 'field_id={"key": "value"}'`
-**Note:** By default, `--set` only parses JSON objects/arrays. Use `--set-json` if you need scalar JSON values (e.g., `true`, `1`, `null`).
-**Examples:**
-1.  **Select List (Single Choice):**
-    ```bash
-    --set 'customfield_15200={"value": "SA"}'
-    ```
-2.  **Select List (Multiple Choice):**
-    ```bash
-    --set 'customfield_12345=[{"value": "Option A"}, {"value": "Option B"}]'
-    ```
-3.  **Cascading Select:**
-    ```bash
-    --set 'customfield_98765={"value": "Parent Option", "child": {"value": "Child Option"}}'
-    ```
-### Validation (Dry Run)
-Use the `--dry-run` flag to validate your payload and check for missing required fields without creating a ticket.
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli jira create \
-  --project NTTC \
-  --issuetype Task \
-  --summary "Test Ticket" \
-  --dry-run
-```
-**Output:**
-```text
-[DRY RUN] Validating payload for NTTC / Task...
-[DRY RUN] ⚠️  Warning: The following REQUIRED fields appear missing:
-  - Vai trò - Công đoạn (customfield_15200)
-Tip: Use --set to provide them.
-```
-The JSON response also includes `field_name_map` to help map field IDs to display names.
-## Configuration
-The orchestrator uses environment variables from the shared VDS env file:
-```bash
-# Required for authentication
-VDS_USERNAME=your-username
-VDS_PASSWORD=your-password
-# Optional: Use token instead of username/password
-JIRA_TOKEN=your-api-token
-# JIRA base URL (defaults to https://jira.digital.vn)
-JIRA_BASE_URL=https://jira.digital.vn
-```
-## Project Layout
-- `src/vds_jira_orchestrator/config.py` – Environment configuration and settings
-- `src/vds_jira_orchestrator/adapter.py` – JIRA adapter using atlassian-python-api SDK
-- `src/vds_jira_orchestrator/cli.py` – Typer CLI interface
-- `src/vds_jira_orchestrator/errors.py` – Custom error types
-- `src/vds_jira_orchestrator/reporting.py` – JSON/Markdown run reports
-- `tests/` – pytest test suite
-## Feature Coverage
-The orchestrator implements **120+ methods** covering core JIRA operations. For a complete feature coverage reference
-and SDK comparison, see [`ATLASSIAN_FEATURES_REFERENCE.md`](../ATLASSIAN_FEATURES_REFERENCE.md).
-**Current Coverage**: ~90% of atlassian-python-api SDK features
-**Recently Added**:
-- ✅ Application Properties (property get/set, settings advanced) - **NEW**
-- ✅ Issue Archiving (issue-archive, issue-restore) - **NEW**
-- ✅ Bulk Operations (bulk-update, field-append) - **NEW**
-- ✅ Version Management (list, create, update) - **NEW**
-- ✅ User Management (search, groups, deactivate) - **NEW**
-- ✅ Issue Link Types management (list, get, create, update, delete) - **NEW**
-- ✅ Issue Security Schemes (list, get) - **NEW**
-- ✅ Advanced Permission Operations (permissions all/check, permission-scheme, issue-security-scheme) - **NEW**
-- ✅ Agile/Scrum operations (boards, epics) - **NEW**
-- ✅ Board properties and velocity management - **NEW**
-- ✅ Sprint management - **NEW**
-- ✅ Backlog operations - **NEW**
-- ✅ Worklog management (time tracking) - **NEW**
-- ✅ Issue transitions & changelog - **NEW**
-- ✅ Advanced search operations (search with pagination, search-by-filter) - **NEW**
-- ✅ Filter management (list, get, create, update, delete) - **NEW**
-- ✅ Dashboard operations - **NEW**
-- ✅ Reindexing operations - **NEW**
-**Missing High-Priority Features**:
-- None (all high-priority features complete)
-## Advanced Features
-The `JiraAdapter` class provides many additional methods beyond the CLI:
-- **Attachments**: `add_attachment()`, `get_attachments()`, `download_attachments()`
-- **Project Operations**: `get_project()`, `get_project_components()`, `get_project_versions()`
-- **Version Management**: `get_project_versions_paginated()`, `add_version()`, `update_version()`
-  - CLI: `jira version list`, `jira version create`, `jira version update`
-- **User Management**: `get_user()`, `find_users()`, `get_myself()`, `get_user_groups()` (Cloud only),
-  `deactivate_user()` (Jira 8.3.0+)
-  - CLI: `jira user search`, `jira user groups`, `jira user deactivate`
-- **Application Properties**: `get_property()`, `set_property()`, `get_advanced_settings()`
-  - CLI: `jira property get`, `jira property set`, `jira settings advanced`
-- **Issue Archiving**: `issue_archive()`, `issue_restore()`
-- **Bulk Operations**: `bulk_update_issue_field()`, `issue_field_value_append()`, `match_jql()`
-  - CLI: `jira bulk-update`, `jira field-append`
-- **Custom Fields**: `get_custom_fields()`, `get_issue_field_value()`
-- **Group Management**: `create_group()`, `remove_group()`, `add_user_to_group()`
-- **Agile Boards**: `get_all_agile_boards()`, `create_agile_board()`, `get_agile_board()`, `get_issues_for_board()`
-- **Board Properties**: `get_agile_board_properties()`, `set_agile_board_property()`,
-  `get_agile_board_refined_velocity()`
-- **Epics**: `epic_issues()`, `get_epics()`, `get_issues_for_epic()`
-- **Sprints**: `get_all_sprints_from_board()`, `create_sprint()`, `rename_sprint()`, `add_issues_to_sprint()`
-- **Reindexing**: `reindex()`, `reindex_status()`, `reindex_with_type()`
-These can be accessed programmatically by importing the adapter:
-```python
-from vds_jira_orchestrator.adapter import JiraAdapter
-from vds_jira_orchestrator.config import JiraSettings
-settings = JiraSettings()
-adapter = JiraAdapter(
-    url=str(settings.base_url),
-    username=settings.username,
-    password=settings.password
-)
-issues = adapter.jql("project = NTTC", limit=100)
-```
-## Run Reports
-Run reports are written to `WHO-project/vds-scripts/reports/jira_runs/YYYY/MM/DD/<timestamp>.json` (plus Markdown unless
-`--no-markdown` is used).
-## Linting
-We use Ruff for linting/formatting:
-```bash
-uv run --extra dev ruff check
-uv run --extra dev ruff format
-```
-## Testing
-```bash
-# Run all tests
-uv run --extra dev pytest
-# Run specific test file
-uv run --extra dev pytest tests/test_cli.py
-# Run with coverage
-uv run --extra dev pytest --cov=src/vds_jira_orchestrator
-```
-## Error Handling
-The orchestrator provides structured error types:
-- `JiraAuthError` - Authentication failures
-- `JiraNotFound` - Resource not found (404)
-- `JiraRateLimited` - Rate limit exceeded (429)
-- `JiraConflictError` - Conflict errors (409)
-- `JiraResponseError` - Server errors (500)
-- `JiraTransportError` - Network/connection errors
-- `JiraAdapterError` - General adapter errors
-All errors include context information for debugging.
- errors include context information for debugging.