Migrate Application

The migrate command converts recognized legacy SDK metadata and instance sync files in the current directory to the current layout.

Bash

zeysdk migrate [options]

Options

Option	Description
--link	Link application after migration
--verbose	Show detailed output

Directory Structure Migration

The command recognizes these legacy files:

• .zeysdk.assets.json
• .zeysdk.package.json
• .zeysdk.sync.<INSTANCE_ID>.json, where the instance ID is a safe SDK identifier

It updates them toward this structure:

Text

my-app/
|-- .zeysdk/
|   |-- sync.json                 # Active link, created later by link/use
|   `-- sync.<INSTANCE_ID>.json   # Migrated non-active instance state
|-- assets/
|-- resources/
|-- services/
|-- settings/
|-- weblets/
`-- zeyos.app.json

Process

1. Pre-migration Validation

   • Requires at least one recognized legacy package, assets, or instance sync file
   • Requires each JSON metadata file, including an existing zeyos.app.json, to contain a JSON object
   • Requires the merged manifest to contain identifier and name
   • Refuses to overwrite an existing .zeysdk/sync.<INSTANCE_ID>.json destination

2. Configuration Migration

   • Merges existing zeyos.app.json, then .zeysdk.assets.json, then .zeysdk.package.json
   • Later sources win when the same property appears more than once
   • Writes the merged result atomically to zeyos.app.json

3. Directory Migration

   • Creates .zeysdk when needed
   • Moves .zeysdk.sync.<INSTANCE_ID>.json to .zeysdk/sync.<INSTANCE_ID>.json
   • Removes the legacy package and assets files after the new manifest succeeds
   • Preserves existing asset directories and files

4. Rollback and Optional Linking

   • Stages legacy metadata files and records moved sync files while migration is in progress
   • Restores moved files and the previous manifest if migration fails
   • Runs the normal interactive zeysdk link flow only after migration succeeds when --link is used
   • Does not roll the completed file migration back if that later link step fails

Examples

Bash

zeysdk migrate
zeysdk migrate --link
zeysdk migrate --verbose

Error Handling

Error	Description	Resolution
No legacy inputs	No recognized legacy files were found	Run from the legacy app root and verify filenames
Invalid metadata	A JSON file is not an object or merged metadata lacks identifier/name	Repair the legacy metadata before retrying
Sync conflict	A destination sync file already exists	Reconcile the old and current sync files manually
Permission denied	Cannot modify files	Check file permissions
Migration conflict	Incompatible changes	Resolve conflicts manually
Link failed	Post-migration link failed	Check instance credentials

Notes

• Migration does not move credentials or create an active .zeysdk/sync.json; use --link, zeysdk link, or zeysdk use as appropriate afterward
• Successful migration removes the recognized legacy metadata files; a cleanup failure can leave a .migrating-<id> file and emits a warning
• --link validates and saves an instance connection after file migration
• --verbose shows detailed progress information

Best Practices

• Commit or manually copy the legacy hidden files before migration; the normal snapshot glob does not include root files such as .zeysdk.assets.json
• Review generated zeyos.app.json before pushing changes
• Run zeysdk compare after migration to inspect local and remote differences
• Commit the migrated structure separately from feature changes