feat(cli): Print report on failure

otdfctl/cmd/migrate/namespaced_policy.go

@@ -93,6 +93,7 @@ func executeNamespacedPolicyCommit(cmd *cobra.Command, h namespacedpolicy.Execut
 	}
 
 	if err := executor.Execute(cmd.Context(), plan); err != nil {
+		writeNamespacedPolicySummary(plan, true, "failure")
 		cli.ExitWithError("could not execute namespaced-policy commit", err)
 	}
 }

otdfctl/docs/man/migrate/namespaced-policy.md

@@ -10,10 +10,14 @@ command:
       default: ''
 ---
 
+## General Information
+
 `namespaced-policy` is the migration entrypoint for moving legacy policy objects into namespaced policy.
 
 The command prints a human-readable migration summary to stdout. Dry runs show the plan summary; `--commit` shows the committed summary with created target IDs.
 
+Commit mode can partially apply changes before an error occurs. When that happens, the command prints a committed summary with `Result: failure` and per-scope `Created`, `Will Create`, and `Failed` sections so you can see what was applied and what still remains.
+
 `--scope` is required and selects any subset of `actions`, `subject-condition-sets`, `subject-mappings`, `registered-resources`, and `obligation-triggers`.
 
 The parent `migrate` command provides the shared `--commit` and `--interactive` flags.
@@ -22,9 +26,41 @@ The parent `migrate` command provides the shared `--commit` and `--interactive`
 
 All target namespaces must already exist before the command runs. Planning should fail before any writes if a required namespace is missing.
 
+## Pre-requisites
+
+1. Run at least `v0.14.0` of the OpenTDF platform before using this migration.
+
+2. Standard actions are seeded per namespace in that platform version. The migration expects those namespaced standard actions to exist when migrating references to `create`, `read`, `update`, and `delete`.
+
+## Best practices
+
+1. Before running any migration commands you should take a backup of your database to avoid any potential issues.
+
+2. While we allow you to perform a full migration of policy at once with the multiple scopes, we recommend that you migrate one-by-one in the following order:
+   - Actions
+   - Subject-Condition-Sets
+   - Subject-Mappings
+   - Obligation-Triggers
+   - Registered-Resources
+
+3. Use `--interactive` mode when migrating policy, this will give you the best chance of success for handling any issues that might occur. In addition, we ask for confirmation for each
+object before creating it.
+
+4. Turn on the `namespaced_policy` feature flag within your deployed service yaml to avoid creating any accidental non-namespaced policy objects.
+
+5. In `--interactive` mode only create operations are reviewed. Existing standard objects and already migrated objects are not prompted.
+
 ## Examples
 
 ```shell
 otdfctl migrate namespaced-policy --scope=registered-resources
 otdfctl migrate namespaced-policy --scope=actions,subject-mappings,registered-resources --commit
+otdfctl migrate namespaced-policy --scope=actions,subject-mappings --interactive --commit
 ```
+
+## Other information
+
+1. For subject-condition-sets and actions, if they are not used by any other policy object they will not be migrated or considered for migration.
+2. If you provide a parent scope, the dependent scopes will also be added. For example, given scope `subject-mappings` will also add scope: `actions`, `subject-condition-sets`
+since those are required by `subject-mappings` to be migrated to a new namespace.
+3. In `--interactive --commit` mode, declining the backup confirmation or aborting review prints an `aborted` summary and exits without applying the remaining changes.

otdfctl/migrations/namespacedpolicy/registered_resources_execute.go

@@ -60,7 +60,7 @@ func (e *Executor) createRegisteredResourceTarget(ctx context.Context, plan *Reg
 
 	// Create the parent RR only when the plan did not already select an existing
 	// target RR to reuse for this namespace.
-	created, hasExistingParent, err := e.existingRegisteredResource(ctx, target)
+	created, hasExistingParent, err := e.existingRegisteredResource(ctx, target) // ? We should remove this right? As we don't currently check. We should just try to create and fail if so.
 	if err != nil {
 		target.Execution = &ExecutionResult{
 			RunID:   e.runID,