[bradclawsie]

Description

CLI-225 asks that a skill be constructed that will migrate legacy bundle manifests to Bundles Next HCL. This PR provides a skill and instructional material on how to use it.

We can't unit test this and there are quite a few judgement calls made to make the migration useful and easy to use, so taste considerations are important when reviewing this PR.

Users will be able to see the skill printed out in full at:

CLI_FEATURES=NextMode=true uds tools migrate-bundle skill.

It is the agent itself that will be running that command though; getting an agent to discover and use this prompt is part of the help documentation printed at:

CLI_FEATURES=NextMode=true uds tools migrate-bundle skill --help.

For example, following the documentation from CLI_FEATURES=NextMode=true uds tools migrate-bundle skill --help, we can copy/paste and slightly modify (to reference our specific legacy file) the instructions to perform this migration:

Run "CLI_FEATURES=NextMode=true uds tools migrate-bundle skill" and use its
printed instructions to migrate
testdata/legacy/bundles/14-optional-components/uds-bundle.yaml.

Write the migrated files and migration report in the current working
directory. Preserve the Legacy input. Do not run any other UDS commands
or use a cluster.

This produces this migated file as bundle.uds.hcl:

uds {
  bundle_api_version = "uds.dev/v1alpha1"
}

metadata {
  name        = "optional-components"
  description = "test bundle with optional components in its pkgs"
  version     = "0.0.1"
}

# Source: uds-bundle.yaml:10-16
package "init" {
  source = "oci://ghcr.io/zarf-dev/packages/init:v0.86.0"

  signature_verification {
    keyless {
      certificate_identity_regexp = "https://github\\.com/zarf-dev/zarf/\\.github/workflows/release\\.yml@refs/tags/v\\d+\\.\\d+\\.\\d+"
      certificate_oidc_issuer     = "https://token.actions.githubusercontent.com"
    }
  }
}

# Source: uds-bundle.yaml:18-22
package "prometheus" {
  source              = "oci://localhost:888/prometheus:0.0.1"
  optional_components = ["upload-image"]
}

# Source: uds-bundle.yaml:24-28
package "podinfo-nginx" {
  source              = "../testdata/legacy/packages/podinfo-nginx"
  optional_components = ["nginx"]
}

Along with this report:
migration-report.md

This skill tested by running through files in testdata.

This PR also adds some automation:

• uds run generate:migration-skill - uses a single source-of-truth for the skill and generates an embeddable file that is used by the cli to emit the skill.
• uds run generate:check-migration-skill - runs the generator tests and checks that the generated file is up to date and there is no drift. CI will also run this check in the lint phase.

CLI_FEATURES=NextMode=true uds tools migrate-bundle skill -o/--output is also available to print the skill to a file.

CONTRIBUTING.md is updated with info on this automation.

Related Issue

Relates to #CLI-225

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Other (security config, docs update, etc)

Checklist before merging

• Test, docs, adr added or updated as needed
• Contributor Guide Steps followed

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds a new CLI command and migration helper tooling.

The PR appears safe to merge; no outstanding finding or new actionable issue was identified.

Summary

The PR adds a self-contained Legacy-to-Next migration prompt to the CLI, guides agents in producing reviewable HCL and a migration report, and adds generation and drift checks for the embedded prompt.

• The revised workflow leaves package trust decisions unresolved when the Legacy bundle supplies no policy.
• The guide separates first-pass migration and artifact creation from later deployment testing.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Skill[Canonical migration skill] --> Generator[Prompt generator]
  Generator --> Asset[Embedded prompt asset]
  Asset --> CLI[uds bundle migrate prompt]
  CLI --> Agent[AI coding agent]
  Legacy[Legacy bundle and local definitions] --> Agent
  Agent --> Outputs[Proposed HCL, values files, and migration report]
  Outputs --> Review[Human review]
  Review --> Create[Optional bundle create]

Loading

_{Reviews (7) · Last reviewed commit: "fix: spdx headers"}

[bradclawsie]

@greptileai review

[bradclawsie]

@greptileai review

[eoghanriley]

Ran into an issue where if I didn't supply a bundle for it to migrate it just didn't do anything and only ran the command to view the prompt. Would be nice if it looked for bundles and asked the user which one they want to be migrated. At a minimum it should raise the issue that a bundle was not supplied.

Executed:

 ``bash
   CLI_FEATURES=NextMode=true ../uds-cli/build/uds bundle migrate prompt
 ``

 The canonical migration skill and included documentation were printed. No repository files were modified and no bundle operations were run.

[eoghanriley]

Ran into another issue, if you have it migrate a bundle in a subdir the miigration report and new bundle are written in the root dir the agent was executed in

[bradclawsie]

Ran into an issue where if I didn't supply a bundle for it to migrate it just didn't do anything and only ran the command to view the prompt.

This is as designed and stated in the --help. The intended use is to take the text from the --help output, and provide it in an agent prompt:

Run the command "CLI_FEATURES=NextMode=true uds bundle migrate prompt" and use its printed instructions to migrate <path-to-legacy-bundle>/uds-bundle.yaml.

Where you are expected to replace <path-to-legacy-bundle> with your bundle. The agent will execute the command as listed above and obtain the full prompt used to accomplish the migration.

[bradclawsie]

Ran into another issue, if you have it migrate a bundle in a subdir the miigration report and new bundle are written in the root dir the agent was executed in

This was the intent. My understanding is, agents get default permissions to create files in the dir they are executing in.

[joelmccoy]

Why was the generation check removed from hk here? f10dfed#diff-16e11e1c2c8588f006bd82a106fc11ea3cbe5b9fce3f8314a5f3944aaddbd0d5

The commit says move this to CI, but hk is run in CI. Why wouldn't we want this as an hk check (that runs in CI automatically)?

[bradclawsie]

Why was the generation check removed from hk here? f10dfed#diff-16e11e1c2c8588f006bd82a106fc11ea3cbe5b9fce3f8314a5f3944aaddbd0d5

The commit says move this to CI, but hk is run in CI. Why wouldn't we want this as an hk check (that runs in CI automatically)?

#1544 (comment)

I believe Eoghan's issue was that it would be a burden to run in local dev with other hk pre-commit hooks.

But you raise a good point. So, I offer e1663ae which puts the check back in to hk, but arranged in hk.pkl checks hooks so it won't be run as a pre-commit hook. I think both of your goals are now met.

[slaskawi]

Generally LGTM. Added one comment and once resolved - I'm happy to approve