@awesomate/hosting-mcp/skill/awesomate-app-builder/references/migrate-from-replit.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# Moving an app from Replit (or Lovable) to Awesomate hosting

The user has a working app somewhere else and their code on their own GitHub.
The job is to make it run on their Awesomate account in three environments,
move the data, and switch their address, without anyone at Awesomate doing a
step by hand. **The hub tells you what is left**: call
`awesomate_app_migration_plan` at the start of every session and after every
step; it returns ordered steps with `done` / `todo` / `blocked` and the tool
or script that completes each one. Follow it rather than this page from
memory.

## Rules that do not bend

- **Never build on the hosting account.** No `npm ci` (without `--omit=dev`),
  no `npm run build`, no `vite build` over SSH. The account has one memory
  ceiling shared by every environment and the user's website; a build there
  is killed mid-run with no useful error. GitHub Actions builds and ships
  artefacts; `awesomate-hosting/scripts/deploy-artifacts.sh` is the manual
  fallback and builds on the user's machine.
- **Never raise a support ticket for these problems yourself.** The hub opens
  one when a rule fires (a secret in the repo, a blocker reported three times,
  a deploy that fails three times in a day) and the plan shows its link. Tell
  the user "Awesomate has been notified and will pick this up" and keep going
  on what you can fix.
- **Dev first, then staging with real data, then prod.** Never push `main`
  before the staging rehearsal passes.

## The sequence (what the plan will walk you through)

1. **Provision the app** if it does not exist: `awesomate_app_create` with
   `kind: 'node'`, template `node-crud-postgres` (Postgres), name from the
   user. Three environments with their own database and `.env` appear.
2. **Link the repo**: `awesomate_app_update { githubRepo: 'owner/repo',
   sourcePlatform: 'replit' }`.
3. **Check the repo**: run
   `node ~/.claude/skills/awesomate-app-builder/scripts/migrate-check.mjs --fix`
   in the clone, then post the JSON with `awesomate_app_repo_check`. Fix
   every `blocker` in the code, re-run, re-post. The common Replit ones:
   - `lockfile_private_registry`: the lockfile resolves packages from
     Replit's mirror. `--fix` regenerates it; commit the result. This is why
     `npm ci` hangs for 14 minutes and dies with an empty log.
   - `neon_serverless_driver`: `@neondatabase/serverless` only talks to
     Neon. Switch to `pg` with `drizzle-orm/node-postgres`.
   - `ready_route_missing`: add `/api/ready` (200 only when `select 1`
     succeeds, else 503). Snippet in the repo's `AWESOMATE.md` after step 4.
   - `port_hardcoded`: `app.listen(Number(process.env.PORT))`.
   - `drizzle_no_generated_sql` (warn): add `drizzle-kit generate` to the
     build, commit `drizzle/`, use the shipped migrate runner. Never `push`.
   - `replit_dev_deps`, `replit_env_reads`, `replit_auth` (warn): remove
     the `@replit/*` plugins, `REPL_ID` reads, and replace Replit Auth.
4. **Add the plumbing**: `awesomate_app_scaffold { appId, mode: 'adopt' }`
   returns only `.github/workflows/deploy.yml`, `.awesomate.json`,
   `scripts/security-check.mjs`, `scripts/awesomate-migrate.mjs` and
   `AWESOMATE.md`. Write them into the repo; touch nothing else. Then edit
   the `deploy` block in `.awesomate.json` to match what the check script
   suggested under `deploy` (artifacts, migrate).
5. **Deploy key**: `node ~/.claude/skills/awesomate-github/scripts/deploy-key.mjs <appId>`
   in the repo. It mints a key for this app, authorises it on the user's
   account, sets the three repo secrets, and records the repo on the hub.
6. **Secrets**: `awesomate_app_set_env` per key per environment. `PORT` and
   `DATABASE_URL` are already there. Replit Secrets map one to one; ask the
   user for values through the awesomate-credentials skill, never in chat.
6b. **Capacity**: `awesomate_app_capacity` before the first deploy and again
   before prod. It reports the account's memory ceiling (shared by every
   environment and the website), the task limit (a Node process costs about
   11), last-day peaks and faults, disk and database sizes, and whether a
   build is running on the account. `blocked` on `nproc_below_floor` or
   `pmem_below_floor` → call again with `fix: true`. Faults, low disk or a
   restart loop are for Awesomate: the hub opens the ticket; tell the user.
7. **Dev**: create and push `dev`; `gh run watch`; `awesomate_app_health`.
   Report the outcome with `awesomate_app_deploy_event` (success or failure,
   with the failing step) so the plan and the stuck-deploy rule see it.
8. **Data into staging**: on the user's machine,
   `pg_dump --no-owner --no-acl "<old DATABASE_URL>" | gzip > dump.sql.gz`,
   then over their jailed SSH (`awesomate-hosting/scripts/ssh-connect.sh`):
   `gunzip -c dump.sql.gz | ssh ... 'set -a; . ~/apps/<slug>-staging/.env; psql "$DATABASE_URL"'`.
   Push `staging`, exercise the real flows on the staging URL.
9. **Prod**: freeze writes on the old platform, repeat the dump into the
   prod database, merge `staging` to `main`, check `/api/ready` and the key
   flows.
10. **Address**: `awesomate_app_domain_attach { appId, hostname:
    'app.theirdomain.com' }`. The hostname must be a subdomain of a domain
    already on the account (their website's domain usually is); the apex and
    `www` stay with the website. It returns the CNAME to set and whether DNS
    already points at us; call it again after they change DNS. Lower the TTL
    before the cutover, then: freeze writes on the old platform, final data
    import, switch the record, check `/api/ready` on the new hostname.
11. **Cleanup**: `awesomate_app_run_state` stopped for dev and staging;
    remove Replit-only files; keep the old platform read-only for a week.

## Lovable

A Lovable app is a Vite React SPA on Supabase. Supabase stays where it is.
The app is `kind: 'static'` here; the build output is the site. The check
script recognises it and stops after the platform section; the static path
does not need the deploy key or the workflow. Full support is a later release.

## What you cannot do

- You cannot put the apex or `www` of their domain on the app; a subdomain
  only (design decision D3). If they insist on the apex, that is a support
  conversation, not a tool call.
- You cannot open a Desk ticket for platform problems; the hub does.
- You cannot lower an account limit or raise it above the platform floors;
  `awesomate_app_capacity fix:true` is raise-only up to the floors.