Skip to content

dynamics-migration-tool

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

dynamics-migration-tool

README.md

BlackBerry Dynamics Migration Tool — Android

Migrate a native Android app to BlackBerry Dynamics using AI-assisted prompts, validation, and structured steering files. Works with Cursor, Kiro, Codex, and other AI coding agents.

Full walkthrough: MIGRATION_INSTRUCTIONS.md

What changed recently: CHANGELOG.md

Prerequisites

  • Android app that builds cleanly (./gradlew assembleDebug)
  • JDK >= 17, Android SDK discoverable via ANDROID_HOME
  • Network access to the BlackBerry Maven repository (no offline mode)
  • Target Dynamics SDK 15.0 (15.0.8513.64 default pin)
  • From your UEM administrator: GDApplicationID and GDApplicationVersion
  • An AI coding agent (Cursor recommended; Kiro, Codex, or generic also supported)

Quickstart

# 1. Copy the tool into your project root
cp -r /path/to/dynamics-migration-tool ./dynamics-migration-tool
chmod +x dynamics-migration-tool/tooling/*.sh

# 2. Run setup (installs steering files for your agent)
./dynamics-migration-tool/tooling/migrate.sh --agent cursor

# 3. Grant IDE permissions (file read/write, shell exec, full network)
#    Cursor: Settings → Cursor Settings → Agents → Auto-Run

# 4. Open an Agent chat and paste the prompt from step 2's output
#    Have GDApplicationID + GDApplicationVersion ready

# 5. After prompt 10 completes, review:
open dynamics-migration-tool/migration-report-viewer.html

# 6. (Optional) When the agent offers prompt 12, opt in to generate:
#    dynamics-migration-tool/output/migration-retrospective.md

Prompt Order

Default sequence (no 00b unless --with-diagrams is passed):

00pre → 00 → 01 → 02 → 03 → 03b → 04 → 05a → 05b → 05c → 06 → 07 → 08 → 09 → 11 → 03c → 10
Step Required? What It Does
00pre Yes Single human stop: IDE permissions, UEM credentials, SDK probe
00 Yes Codebase analysis, execution plan, no code changes
00b Optional Architecture diagrams (opt in with --with-diagrams)
01 Yes Gradle SDK dependency, minSdk, Maven repo
02 Yes settings.json from UEM values
03 / 03b Yes Authorization init + deferral audit
04 if applicable SQLite → secure SQL
05a/05b/05c if applicable Filesystem → GD secure storage (split flow)
06 if applicable Networking → GDHttpClient / GDSocket
07 if applicable WebView → BBWebView
08 if applicable ICC / TransferFileService
09 if applicable UI widgets → com.good.gd.widget.*
11 if applicable FCM / Push Channel hardening (before 03c)
03c if applicable Background Authorize intent per push/job entry point
10 Yes Migration report + human-readable readme
12 Optional Migration run retrospective (after 10; developer opt-in)

Outputs

Artifact Generated By
output/bootstrap.json 00pre
output/migration-analysis.json 00
output/migration-report.json 10
output/runtime-evidence.json tooling/runtime-evidence.sh + runtime QA/automation
output/migration-improvement-backlog.json tooling/improvement-backlog.sh
output/loop-readiness-assessment.json tooling/release-assessment.sh
Dynamics_Migration_Readme.md 10
output/migration-retrospective.md 12 (optional)

Validation

Validation is a final-gate step: prompts before 10 record progress without auto-running validator phases, and prompt 10 runs the mandatory split gate (--mode final-source then --mode report). Manual spot-check:

./dynamics-migration-tool/tooling/validate.sh

The validator checks: settings.json, Gradle deps, authorization wiring, file storage, SQL, networking, UI widgets, ICC, build, migration comments, and report contract. See MIGRATION_INSTRUCTIONS.md for the full check table.

For actionable fix instructions on failures:

./dynamics-migration-tool/tooling/validate.sh --fix-suggestions

Optional Observability

To measure migration efficiency without recording source contents, enable content-free observability before running toolkit commands:

export DYNAMICS_MIGRATION_OBSERVABILITY=1

This writes JSONL events and a summary under dynamics-migration-tool/output/observability/. Disable it by unsetting the environment variable. Observability is best-effort and does not change validation results, prompt gates, or generated reports.

Context Efficiency

Generate a repository manifest when you want the agent to reuse stable context and invalidate changed source/state explicitly:

bash ./dynamics-migration-tool/tooling/generate-repository-manifest.sh

This writes output/repository-manifest.json and output/context-summary.md. The manifest is an index, not a cache; validation gates still run normally.

Repair Orchestrator (optional, maturing)

The repair orchestrator is an optional bounded loop around the recorder and the prompt-scoped validator. It does not edit your source code: it records the prompt, runs scoped validation, and on failure writes a bounded repair task for the agent to apply.

Final acceptance remains recorder-owned: tooling/record-prompt-execution.sh is authoritative for completion, and prompt 10 split final gates (final-source + report) are never delegated to the orchestrator.

bash ./dynamics-migration-tool/tooling/repair-orchestrator.sh --prompt-id <id>

Exit codes drive the loop:

  • 0 — recorded and validated; continue to the next prompt.
  • 1 — output/repair-task.md was written; apply the owning prompt to the listed files, then re-invoke for the same prompt.
  • 3 — escalated (budget exhausted, no-progress, or an owner decision); stop and involve a developer.
  • 2 — prompt is outside the controlled Stage 7 subset; run the owning recorder path directly (for prompt 10, use the standard record call).

Budgets, no-progress detection, and escalations are enforced across invocations and recorded in output/repair-orchestrator-state.json; terminal escalations are reflected into output/migration-loop-state.json. See steering/96-repair-loop-conduct.md for the full conduct rules. The loop is maturing and optional; it never overrides a validator or approves a trust-boundary decision.

Reviewer Lane (optional, read-only)

The reviewer lane is an independent, read-only risk review of the migration artifacts. It cites concrete evidence and produces advisory findings; it never overrides deterministic validators.

bash ./dynamics-migration-tool/tooling/reviewer-lane.sh

This writes output/reviewer-lane.json and output/reviewer-lane.md. Use it for security-sensitive migrations, repeated repair attempts, unsupported-feature removal, or insufficient runtime evidence.

Runtime Evidence

Runtime evidence is a structured record of device/UEM validation. Create a starter artifact, fill it from QA or automation, then validate it:

bash ./dynamics-migration-tool/tooling/runtime-evidence.sh init-template
bash ./dynamics-migration-tool/tooling/runtime-evidence.sh validate

Use blocked or pending when a device, UEM environment, policy, or human action is unavailable. Do not mark runtime checks as passed without an observed result and evidence reference.

Improvement Backlog

Generate an advisory learning-loop backlog after validation, repair, reviewer, or runtime evidence artifacts exist:

bash ./dynamics-migration-tool/tooling/improvement-backlog.sh

This writes output/migration-improvement-backlog.json and .md. Candidates are not applied automatically; every prompt, steering, validator, or implementation change still requires maintainer review, a regression fixture, and deterministic acceptance evidence.

Release Assessment

Generate a conservative benchmark/readiness assessment from current artifacts and optional representative benchmark cases:

bash ./dynamics-migration-tool/tooling/release-assessment.sh

Use --benchmark-dir <dir> to provide Tier A/Tier B benchmark case JSON files. Without representative corpus evidence, the assessment reports further hardening rather than production readiness. The Stage 7 repair orchestrator is treated as a maturing lane and remains optional/controlled.

Progress & Recovery

# Check progress mid-run
./dynamics-migration-tool/tooling/progress.sh

# Inspect retry/escalation state when loops are suspected
cat dynamics-migration-tool/output/migration-loop-state.json

# Resume from last completed prompt
./dynamics-migration-tool/tooling/migrate.sh --resume --agent cursor

# Restore app sources from the backup branch created by prompt 00pre
git branch --list "migration-backup-*"
git checkout <migration-backup-branch> -- .

# Or restore a single path from the backup branch
git checkout <migration-backup-branch> -- path/to/file

Agent Setup

Agent Command
Cursor ./dynamics-migration-tool/tooling/migrate.sh --agent cursor
Kiro ./dynamics-migration-tool/tooling/migrate.sh --agent kiro
Codex ./dynamics-migration-tool/tooling/migrate.sh --agent codex
Generic ./dynamics-migration-tool/tooling/migrate.sh

Project Shapes Supported

  • Single-module (app/) — zero config
  • Multi-module (single application module) — auto-discovered
  • Multi-application — pass --app-module <name> to bootstrap
  • Convention-plugin projects — edits plugin source files directly

Kotlin Multiplatform modules are recorded but skipped by this release.

Kit Structure

  • prompts/ — step-by-step migration prompts (run in order)
  • steering/ — AI agent context installed as project rules
  • tooling/ — CLI scripts (migrate, bootstrap, validate, record)
  • output/ — generated artifacts (commit alongside source)
  • _maintainer/ — internal diagnostics, not installed for third-party devs

Links

Apache 2.0 — See LICENSE file.