nocobase-publish-manage

What this skill does

# 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](references/v1-runtime-contract.md) for exact command construction and parsing rules.

# Reference Loading Map

| Reference | Use When |
|---|---|
| [Intent Routing](references/intent-routing.md) | Mapping user phrases to backup, migration, file reuse, and environment shape. |
| [Runtime Contract](references/v1-runtime-contract.md) | Building commands and carrying names, paths, rules, and status between steps. |
| [Test Playbook](references/test-playbook.md) | 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:

```text
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:

```text
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>` an