From 4664100cdb5465e849b6219dcd1a1e6fd14c3157 Mon Sep 17 00:00:00 2001 From: Nikhil Agashe Date: Thu, 9 Jul 2026 22:08:44 +0000 Subject: [PATCH] feat(aws-transform): continuous-modernization updates - 250-repo cap with splitting, version-agnostic pagination, background logs to /tmp, blocking --wait + nextToken pagination, remediation-cap wording - Bump POWER.md version to 2.3.0 --- aws-transform/POWER.md | 2 +- ...kload-continuous-modernization-analysis.md | 33 ++++++++++++++++--- ...kload-continuous-modernization-findings.md | 15 +++++++++ ...ad-continuous-modernization-remediation.md | 30 +++++++++++++++-- ...load-continuous-modernization-reporting.md | 6 +++- ...orkload-continuous-modernization-source.md | 4 +++ 6 files changed, 82 insertions(+), 8 deletions(-) diff --git a/aws-transform/POWER.md b/aws-transform/POWER.md index 4964dd3..ca22a82 100644 --- a/aws-transform/POWER.md +++ b/aws-transform/POWER.md @@ -4,7 +4,7 @@ displayName: "AWS Transform" description: "Migrate, modernize, and upgrade codebases: .NET Framework to .NET 8/10, mainframe COBOL to Java, VMware VMs to EC2, SQL Server/Oracle/MySQL to Aurora, and Java/Python/Node.js version upgrades or AWS SDK migrations. Assess, plan, and execute code transformations from your IDE." keywords: ["migrate", "modernize", "mainframe", "cobol", "vmware", "dotnet", ".net framework", "windows", "sql server", "oracle", "mysql", "aurora", "ec2 migration", "rehost", "lift-and-shift", "replatform", "legacy", "code upgrade", "sdk migration", "boto3", "java upgrade", "atx", "continuous modernization", "AWS Transform - continuous modernization"] author: "AWS" -version: "2.2.0" +version: "2.3.0" --- # AWS Transform Power diff --git a/aws-transform/steering/workload-continuous-modernization-analysis.md b/aws-transform/steering/workload-continuous-modernization-analysis.md index 719466a..3931499 100644 --- a/aws-transform/steering/workload-continuous-modernization-analysis.md +++ b/aws-transform/steering/workload-continuous-modernization-analysis.md @@ -33,15 +33,21 @@ If the user explicitly asks to disable telemetry, omit `--telemetry` for the res - **EC2** -- follow [continuous-modernization-ec2-execution](workload-continuous-modernization-ec2-execution.md) - **Batch** -- follow [continuous-modernization-batch-execution](workload-continuous-modernization-batch-execution.md) +## Repository limit per request (max 250) + +A single `atx ct analysis run` can be associated with at most **250 repositories**. Before starting an analysis that targets many repos (for example a whole source), check how many repositories are in scope — `atx ct source list` or `atx ct repository list --source ` report the per-source count. (Bare `atx ct status` shows workspace-wide totals across all sources, so prefer a scoped form when the analysis targets a single source.) + +If the scope exceeds 250 repositories, split it into multiple runs, each targeting at most 250 repos (pass the repos in batches via `--repo ::`), and tell the user you are breaking the work up because of the 250-repo-per-request limit. Never issue a single run associated with more than 250 repositories — it will be rejected. Example: 300 repos → two runs (250 + 50); 600 repos → three runs (250 + 250 + 100). + ## Commands ```bash -# Run analysis (returns immediately with analysis ID) -atx ct analysis run --type --source [--repo ::] --telemetry "agent=,executionMode=local" - -# Run and wait for completion +# Run analysis. Pass --wait so the command blocks until the run finishes (preferred — see "Running long analyses" below). atx ct analysis run --type --source [--repo ::] --wait --telemetry "agent=,executionMode=local" +# --wait is only in newer CLI versions. If it isn't supported, run the same command without --wait. +atx ct analysis run --type --source [--repo ::] --telemetry "agent=,executionMode=local" + # Run custom analysis with a specific transformation definition atx ct analysis run --type custom --transformation-name --source --repo :: --wait --telemetry "agent=,executionMode=local" @@ -67,6 +73,21 @@ atx ct analysis cancel --id atx ct analysis delete --id [--cascade-findings] ``` +## Running long analyses (--wait, background, logs) + +`atx ct analysis run` returns immediately by default with an analysis ID. With `--wait` it blocks until the run completes — and a comprehensive or multi-repo run can take a long time. Prefer `--wait` so the run blocks to completion and you can act on the result in the same step. + +**`--wait` is version-gated.** It exists only in newer CLI versions. Before relying on it, confirm the installed CLI supports it — check `atx ct analysis run --help` (or `atx ct --version`). If `--wait` isn't listed, run the command without it; do not invent the flag. If a run fails with an unknown-option error for `--wait`, re-run without it. + +**Run long jobs in the background and monitor a log.** A blocking run ties up the session, so start long-running analyses in the background with `&`, redirect output to a log file, and monitor the log: + +```bash +atx ct analysis run --type tech-debt-comprehensive --source --wait --telemetry "agent=,executionMode=local" > /tmp/atx-analysis.log 2>&1 & +tail -f /tmp/atx-analysis.log +``` + +This applies to comprehensive scans, large multi-repo runs, and any analysis the user expects to take a while. Tell the user where the log is and how to check progress. + ## Custom Analysis The `custom` type runs any transformation definition (TD) against a repository. Unlike other analysis types, custom analysis does not generate findings -- it executes the TD directly. @@ -198,3 +219,7 @@ If an analysis returns 0 findings on a repo that's obviously stale (Java 8, Node `--category` is a client-side grouping; e.g. `"Tech Debt"` matches both `tech-debt-quick` and `tech-debt-comprehensive`. Use it when the user wants both subtypes together. `--status` and `--type` accept only the canonical values above. Off-canonical input (e.g. `--status completed`, `--type tech-debt`) returns an `INVALID_INPUT` error. + +### Pagination (nextToken) + +Depending on the CLI version, `atx ct analysis list` may return only a bounded page rather than every result — don't assume a fixed response shape. After each call, check whether the response carries a `nextToken`; if it's present and non-empty, call the command again with `--next-token ` and repeat until no `nextToken` remains. Never treat the first page as the complete set when a `nextToken` is present, or you'll silently miss analyses. diff --git a/aws-transform/steering/workload-continuous-modernization-findings.md b/aws-transform/steering/workload-continuous-modernization-findings.md index 9c19a83..4d66562 100644 --- a/aws-transform/steering/workload-continuous-modernization-findings.md +++ b/aws-transform/steering/workload-continuous-modernization-findings.md @@ -49,6 +49,20 @@ atx ct findings batch-update --ids --status --rea atx ct findings delete --id ``` +## Pagination (nextToken) + +Depending on the CLI version, `atx ct findings list` may return only a bounded page rather than every finding — so don't assume a fixed response shape. After each call, check whether the response carries a `nextToken`. If it's present and non-empty, the results are truncated: call the same command again with the same filters plus `--next-token `, and repeat until the response has no `nextToken`. Concatenate the pages before answering. If there's no `nextToken`, you already have the full set. + +```bash +# First page +atx ct findings list --status open --json +# ...response includes "nextToken": "" → fetch the next page +atx ct findings list --status open --json --next-token +# ...repeat until the response has no nextToken +``` + +Never present the first page as the complete set when a `nextToken` is present — that silently drops findings and undercounts severity totals. + ## Status set `open`, `dismissed`, `obsolete`. Transitions a user can drive: `open ↔ dismissed`. `obsolete` is a terminal state set by the system when a re-analysis no longer produces the finding — users do not transition into or out of it. @@ -75,6 +89,7 @@ Filtering at the CLI is materially faster than pulling everything and filtering - "Auto-fixable" without a transform name → narrow with `--type tech-debt-quick` first. `tech-debt-quick` findings carry an ATX-transform fix; `security` findings carry a security-agent fix (see the [remediation](workload-continuous-modernization-remediation.md) skill). Findings without a `fix` field may still be remediable — see the [remediation](workload-continuous-modernization-remediation.md) skill's decision tree. - `--type` alone or `--type --severity`/`--type --min-severity` (no status, no repo) → add `--status open` to anchor on the live-triage shape. - Passing both `--severity` and `--min-severity` in the same call → the CLI rejects this. Pick one. +- Treating the first page of `atx ct findings list` as the complete set when the response carries a non-empty `nextToken`. Page through with `--next-token ` until no `nextToken` remains — otherwise you silently drop findings. ### Multi-repo, multi-type questions diff --git a/aws-transform/steering/workload-continuous-modernization-remediation.md b/aws-transform/steering/workload-continuous-modernization-remediation.md index 500c758..327b510 100644 --- a/aws-transform/steering/workload-continuous-modernization-remediation.md +++ b/aws-transform/steering/workload-continuous-modernization-remediation.md @@ -27,8 +27,9 @@ Format: `--telemetry "agent=,executionMode="` If the user explicitly asks to disable telemetry, omit `--telemetry` for the rest of the session. ```bash -# Create from finding IDs (uses each finding's fix.transform_name) -atx ct remediation create --ids --name "Fix name" --telemetry "agent=,executionMode=local" +# Create from finding IDs (uses each finding's fix.transform_name). +# Pass --wait so the command blocks until the remediation finishes (version-gated — see "Running long remediations" below). +atx ct remediation create --ids --name "Fix name" --wait --telemetry "agent=,executionMode=local" # Create from finding IDs with a custom TD override (ignores finding's fix field) atx ct remediation create --ids --transformation-name --telemetry "agent=,executionMode=local" @@ -55,6 +56,31 @@ atx ct remediation retry --id atx ct remediation delete --id ``` +## Repository limit per request (max 250) + +A single `atx ct remediation create` can be associated with at most **250 repositories**. Before creating a remediation that spans many repos, check how many distinct repositories the target findings cover. + +If the remediation would span more than 250 repositories, split it into multiple `remediation create` requests, each covering findings from at most 250 repos, and tell the user you are breaking it up because of the 250-repo-per-request limit. Never create a single remediation associated with more than 250 repositories — it will be rejected. Example: findings across 300 repos → two remediations (one for 250 repos, one for the remaining 50). + +## Running long remediations (--wait, background, logs) + +`atx ct remediation create` returns immediately by default with a remediation ID. With `--wait` it blocks until the remediation completes — and applying transforms across repos can take a long time. Prefer `--wait` so you can act on the result in the same step. + +**`--wait` is version-gated** — it exists only in newer CLI versions. Confirm support via `atx ct remediation create --help` (or `atx ct --version`) before relying on it; if it isn't listed, run without `--wait` and do not invent the flag. If a run fails with an unknown-option error for `--wait`, re-run without it. + +**Run long jobs in the background and monitor a log.** Start long-running remediations with `&`, redirect output to a log file, and monitor it: + +```bash +atx ct remediation create --ids --name "Fix name" --wait --telemetry "agent=,executionMode=local" > /tmp/atx-remediation.log 2>&1 & +tail -f /tmp/atx-remediation.log +``` + +Tell the user where the log is and how to check progress. + +## Listing remediations (pagination) + +Depending on the CLI version, `atx ct remediation list` may return only a bounded page — don't assume a fixed response shape. After each call, if the response carries a non-empty `nextToken`, call the command again with `--next-token ` and repeat until no `nextToken` remains. Don't treat the first page as complete when a `nextToken` is present. + ## Security Remediation Security findings (from `atx ct analysis run --type security`) are auto-remediable with the **same** `remediation create` command as any other finding — no `--transformation-name` is needed. Security findings carry a `security-agent` fix, which routes to the AWS Security Agent code-remediation API instead of an ATX transform; the fix is generated server-side. diff --git a/aws-transform/steering/workload-continuous-modernization-reporting.md b/aws-transform/steering/workload-continuous-modernization-reporting.md index c1f59d3..5255c95 100644 --- a/aws-transform/steering/workload-continuous-modernization-reporting.md +++ b/aws-transform/steering/workload-continuous-modernization-reporting.md @@ -26,9 +26,13 @@ atx ct findings list --json atx ct remediation list --json ``` +### Paginate every list to completion (nextToken) + +Response shape can vary by CLI version, so don't hard-code it: a list command may return every result at once, a bare array, or an object that wraps the array alongside a top-level `nextToken`. The report is a **static snapshot baked from this data**, so a dropped page silently loses sources, repos, analyses, findings, or remediations. The version-agnostic rule: after each list call, check whether the response carries a non-empty `nextToken`; if it does, call the command again with `--next-token ` and repeat until no `nextToken` remains, then concatenate all pages before normalizing. If there is no `nextToken`, the single response is already complete. A truncated `findings` or `remediation` fetch skews every KPI and chart downstream. + ### Raw response shapes -The five commands do NOT return the same envelope. Read each carefully — `repository list` wraps results in `{"items": [...]}`; the other four return a flat array. All field names are snake_case. +The five commands do NOT return the same envelope, and the exact container can vary by CLI version — `repository list` wraps results in `{"items": [...]}`, while the others may come back as a bare array or (on newer CLIs) an object wrapping the array alongside a `nextToken` (see the pagination note above). Read the records wherever they live and follow `nextToken` when it's present. The shapes below describe the objects **inside** each list. All field names are snake_case. **`source list --json`** → flat array: ```jsonc diff --git a/aws-transform/steering/workload-continuous-modernization-source.md b/aws-transform/steering/workload-continuous-modernization-source.md index 3ed691a..c5fb2b6 100644 --- a/aws-transform/steering/workload-continuous-modernization-source.md +++ b/aws-transform/steering/workload-continuous-modernization-source.md @@ -118,6 +118,10 @@ atx ct repository update --source --labels "migration:v2" atx ct repository delete --repo "::" --source ``` +## Pagination (nextToken) + +Depending on the CLI version, `atx ct source list` and `atx ct repository list` may return only a bounded page — don't assume a fixed response shape. After each call, if the response carries a non-empty `nextToken`, call the command again with `--next-token ` (keeping any `--source`/`--labels` filters) and repeat until no `nextToken` remains. Don't treat the first page as the complete set — otherwise sources or repos silently go missing from listings and downstream scoping. + ## Labels Labels are user-defined identifiers for organizing and filtering groups of repositories.