Skip to content

feat: add migration package contract#35

Merged
zdburrage merged 3 commits intomainfrom
feat/package-contract
May 1, 2026
Merged

feat: add migration package contract#35
zdburrage merged 3 commits intomainfrom
feat/package-contract

Conversation

@zdburrage
Copy link
Copy Markdown
Collaborator

@zdburrage zdburrage commented Apr 29, 2026

Summary

Adds the provider-neutral migration package contract that future provider exporters and import-package orchestration can share.

This includes:

  • Canonical package file paths and CSV headers
  • Manifest types and creation helpers
  • Package writer/loader helpers
  • Package validator for manifest shape, canonical paths, CSV headers, JSONL parseability, and count consistency
  • Customer-facing migration package documentation
  • Ignored local ideation/planning directories

Impact

Existing single-CSV import/export behavior is unchanged. This branch only adds the package foundation and generated dist output.

Stack

This is PR 1 of 3. Merge order:

  1. feat/package-contract
  2. feat/sso-handoff-shared
  3. feat/auth0-package-core

Bug fix: double-counting entity count aliases

Fixed a bug where COUNTABLE_FILES and DEFAULT_ENTITY_COUNTS contained alias keys (rolesroleDefinitions, roleAssignmentsuserRoleAssignments) that mapped to the same underlying CSV file. This caused validatePackageCounts to check the same file twice with potentially different expected counts, producing spurious entity_count_mismatch errors. The fix removes the aliases and uses only canonical keys. Updated the example manifest in docs accordingly.

Validation

  • npm run typecheck
  • npm run lint
  • npm run format:check
  • npm test
  • npm run build

Checklist

  • I have run npm run lint, npm run typecheck, npm run build, and npm test locally.
  • I have updated the README or other docs if behavior changed.
  • I have added or updated tests if appropriate.

Link to Devin session: https://app.devin.ai/sessions/6cb6a67c0a7b4347aea738290e855633
Requested by: @zdburrage


Open in Devin Review

@zdburrage zdburrage marked this pull request as ready for review April 30, 2026 19:41
devin-ai-integration[bot]

This comment was marked as resolved.

Remove redundant alias keys (roles, roleAssignments) from
DEFAULT_ENTITY_COUNTS and COUNTABLE_FILES. Both roles and
roleDefinitions mapped to the same file (role_definitions.csv),
causing spurious entity_count_mismatch errors when only one key
was set. Similarly, roleAssignments was an alias for the
userRoleAssignments file key.

Use only canonical keys (roleDefinitions, userRoleAssignments) so
each file is validated exactly once.

Co-Authored-By: zac.burrage <zac.burrage@workos.com>
devin-ai-integration[bot]

This comment was marked as resolved.

Replace removed alias keys (roles, roleAssignments) with canonical
keys (roleDefinitions, userRoleAssignments) in the example manifest.

Co-Authored-By: zac.burrage <zac.burrage@workos.com>
@zdburrage zdburrage merged commit d3290e6 into main May 1, 2026
4 checks passed
@zdburrage zdburrage deleted the feat/package-contract branch May 1, 2026 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant