nocobase/nocobase-publish-manage

Goal

Orchestrate NocoBase backup restore and migration workflows with the current API CLI command surface.

The skill converts user intent into an API-first publish context, carries generated names and local paths between steps, and requires explicit confirmation before restore or migration execution changes target data.

Scope

• Backup list, create, status, download, remove, restore, restore-upload, and restore-status through nb api backup.
• Migration file list, get, create, download, remove, check, and execute through nb api migration.
• Migration rule list, get, and global rule create through nb api migration rules.
• Migration log list, get, and download through nb api migration logs for diagnosis.
• Same-environment and cross-environment workflows. The default test workflow uses source_env=dev and target_env=dev.
• Planning, dry explanation, read-only validation, and failure diagnosis from command output.

Non-Goals

• This skill focuses on the API CLI command surface listed in Scope.
• Package and rule selection stays explicit.
• Restore, execute, and remove actions stay behind the execution confirmation gate.
• Failure recovery preserves the current context and waits for user direction before a new package or rule is created.

Input Contract

| Input | Required | Default | Validation | Clarification | |---|---|---|---|---| | action | yes | inferred | plan, run, or validate | "Should I plan, run, or validate the workflow?" | | method | run: yes | inferred | backup or migration | "Use backup restore or migration publish?" | | source_env | conditional | dev for tests | non-empty env name | "Which environment provides or generates the file?" | | target_env | run: yes | dev for tests | non-empty env name | "Which environment should receive and execute the file?" | | backup_name | optional | unset | backup file name from backup list/create | "Which server backup should be restored or downloaded?" | | migration_name | optional | unset | migration file name from migration list/create | "Which server migration package should be downloaded?" | | local_file | optional | unset | readable local .nbdata path | "Which local package file should be uploaded or executed?" | | cli_home | optional | CLI global home | writable CLI home directory | "Which CLI home should store downloaded release files?" | | rule_id | migration create only | unset | non-empty id | "Which migration rule ID should be used?" | | migration_user_rule | migration rule create only | schema-only | schema-only or overwrite | "How should user-defined tables be handled?" | | migration_system_rule | migration rule create only | overwrite-first | overwrite-first or schema-only | "How should system tables be handled?" | | title | migration create only | publish-<source>-to-<target> | non-empty text | "Which migration title should be used?" | | execute_options | optional | safe CLI defaults | known nb api backup restore* or nb api migration execute flags | "Any high-risk flags such as --skip-backup or --skip-revert-on-error?" | | confirm_publish_input | before create/download/rule create/check | unset | explicit approval | "Confirm the selected input before I create, download, or check the package." | | confirm_execute | before restore/execute/remove | unset | must be confirm | "Type confirm to execute on the target environment." |

Mandatory Clarification Gate

• Max clarification rounds: 2.
• Ask at most 3 short questions per round.
• Mutation steps require resolved method, source_env, and target_env.
• Migration package creation requires a selected or newly created rule_id.
• Existing package list flows require user selection of a specific file.
• Package create, package download, migration rule create, and migration check require publish input confirmation.
• Backup restore, backup restore-upload, backup remove, migration execute, and migration remove require execution confirmation.
• If the user says "you decide", choose a read-only planning path.

Workflow

1. Route intent to backup or migration.
2. Build a context with method, sourceEnv, targetEnv, cliHome, releaseDir, backupName, migrationName, localFile, downloadPath, ruleId, title, and step.
3. Run read-only capability probes for the needed command groups. Treat 404, Not Found, unknown resource, inactive plugin, or license capability errors as unsupported_publish_env.
4. For backup restore:
   • Local file: confirm the file, then restore it with nb api backup restore-upload --file <localFile> -e <targetEnv> --force.
   • Server backup on target: confirm the backup name, then restore it with nb api backup restore --name <backupName> -e <targetEnv> --force.
   • Source-to-target: create or select the backup on sourceEnv, download it to <cliHome>/release/<sourceEnv>/<backupName>, then restore-upload that path on targetEnv with --force.
5. For migration:
   • Local file: confirm the file, check it on targetEnv, then execute it on targetEnv.
   • Server migration package: download it from sourceEnv to <cliHome>/release/<sourceEnv>/<migrationName>, check it on targetEnv, then execute it on targetEnv.
   • Created migration package: list or create a global rule, create the migration on sourceEnv, poll migration get until the generated package reports status=ok, download it to <cliHome>/release/<sourceEnv>/<migrationName>, check it on targetEnv, then execute it on targetEnv.
6. Poll or inspect status with available commands when needed: backup status, backup restore-status --task <taskId>, migration get, and migration logs.
7. Treat restore task ids as compatible fields: parse taskId from data.taskId or data.task, then pass that value to backup restore-status --task.
8. Report the final state, commands executed or planned, file names, local paths, failed step, and next verification command.

See Runtime Contract for exact command construction and parsing rules.

Reference Loading Map

| Reference | Use When | |---|---| | Intent Routing | Mapping user phrases to backup, migration, file reuse, and environment shape. | | Runtime Contract | Building commands and carrying names, paths, rules, and status between steps. | | Test Playbook | Validating supported API workflows and failure cases. |

Safety Gate

High-impact actions:

• nb api backup restore
• nb api backup restore-upload
• nb api backup remove
• nb api migration execute
• nb api migration remove
• nb api migration rules create
• any option that skips target backup or revert behavior, such as --skip-backup or --skip-revert-on-error

Publish input confirmation template:

Confirm publish input: <method> from <source_env> to <target_env>. Package source: <existing server file | local file | create new>. Migration rule: <ruleId/name | create new with user-defined-rule/system-defined-rule | not applicable>. Reply `confirm input` to continue with package creation, download, or check.

Execution confirmation template:

Confirm execution: <backup restore | migration execute> on <target_env> using <backupName | migrationName | localFile>. This may change target data. Reply `confirm` to continue.

Failure guidance:

• Backup restore failure: if a restore task id is available from data.taskId or data.task, inspect nb api backup restore-status --task <taskId> -e <targetEnv>.
• Migration package creation: if migration get reports status=in_progress, tell the user the package is still generating, wait, and do not run migration download until status=ok.
• Migration check failure: report the check output and keep the local package path.
• Migration execution failure: inspect nb api migration logs list -e <targetEnv> and relevant logs get/download output.
• Package or rule recreation after a failure requires explicit user instruction.
• Preserve the context in the final response so the user can resume from the correct file or rule.

Verification Checklist

• Publish operations use nb api backup and nb api migration command groups.
• The default test context is sourceEnv=dev and targetEnv=dev.
• Participating environments pass read-only command probes before mutation.
• Capability probe failures are reported as unsupported_publish_env.
• Package lists and migration rule lists lead to explicit user selection.
• Existing local files skip package creation.
• Existing server backup names may use backup restore --name when restoring inside the same target environment.
• Cross-environment backup restore uses backup download followed by backup restore-upload --force.
• Backup restore and restore-upload commands include --force directly.
• Downloaded backup, migration, and log files are stored under <cliHome>/release/<sourceEnv>/.
• Migration execution uses a local package file with migration check --file before migration execute --file.
• Missing migration file triggers migration rule list before asking for or creating rule_id.
• migration rules create uses global rule options.
• Created or selected migration rules are verified with migration rules get when possible.
• Download commands include --output.
• Restore status commands include --task <taskId> and are only run after a task id is returned as data.taskId or data.task.
• Restore or execute waits for secondary confirmation.
• Failure output includes the failed step and relevant CLI lines.

References

• Intent Routing
• Runtime Contract
• Test Playbook
• NocoBase Migration Manager: official context for migration risk and publish-related operations. [verified: 2026-04-30]