Add v1-to-v2 profiles.json migration helper #105

New Issue

2026-07-02T17:37:29-05:00

sysadmin commented

2026-07-02 17:37:29 -05:00

Summary

Add a migration helper for converting profiles.json version 1 to version 2.

Source discussion

Refs #100

Scope

Create a migration helper that:

reads existing v1 profiles.json
generates v2 structure
preserves existing keychain auth.id references
writes aliases for old profile names
creates a backup before writing
defaults to dry-run
never reads keychain secret values
never prints secrets
validates the output before writing

Required old-profile compatibility

Existing profile names should continue to work:

mdcps
prgs-author
prgs-reviewer

Suggested alias mapping:

{
  "aliases": {
    "mdcps": "mdcps.gitea.author",
    "prgs-author": "prgs.gitea.author",
    "prgs-reviewer": "prgs.gitea.reviewer"
  }
}

Keychain policy

Old keychain IDs remain valid forever through explicit auth.id.
New keychain items should use dotted naming convention.
This migration helper must not rename, delete, or rewrite keychain entries.

Non-goals

Do not provision new service credentials.
Do not create or modify keychain secrets.
Do not implement Jenkins or GlitchTip service tools.
Do not change release/tag state.

Acceptance criteria

dry-run is default
write mode requires explicit flag
original file is backed up
migrated file validates as v2
aliases preserve old profile names
secrets are never read, printed, or written
malformed v1 input fails safely with a clear message
tests cover dry-run, write mode, backup, alias generation, and no-secret behavior

## Summary Add a migration helper for converting `profiles.json` version 1 to version 2. ## Source discussion Refs #100 ## Scope Create a migration helper that: - reads existing v1 `profiles.json` - generates v2 structure - preserves existing keychain `auth.id` references - writes aliases for old profile names - creates a backup before writing - defaults to dry-run - never reads keychain secret values - never prints secrets - validates the output before writing ## Required old-profile compatibility Existing profile names should continue to work: - `mdcps` - `prgs-author` - `prgs-reviewer` Suggested alias mapping: ```json { "aliases": { "mdcps": "mdcps.gitea.author", "prgs-author": "prgs.gitea.author", "prgs-reviewer": "prgs.gitea.reviewer" } } ``` ## Keychain policy * Old keychain IDs remain valid forever through explicit `auth.id`. * New keychain items should use dotted naming convention. * This migration helper must not rename, delete, or rewrite keychain entries. Suggested new naming convention: ```text prgs.gitea.author.token prgs.gitea.reviewer.token mdcps.gitea.author.token mdcps.gitea.reviewer.token mdcps.jenkins.reader.token mdcps.glitchtip.reader.token ``` ## Non-goals * Do not provision new service credentials. * Do not create or modify keychain secrets. * Do not implement Jenkins or GlitchTip service tools. * Do not change release/tag state. ## Acceptance criteria * dry-run is default * write mode requires explicit flag * original file is backed up * migrated file validates as v2 * aliases preserve old profile names * secrets are never read, printed, or written * malformed v1 input fails safely with a clear message * tests cover dry-run, write mode, backup, alias generation, and no-secret behavior