Rename sync/ directory to sync-local/ to match the command name

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jerico

.claude/worktrees/epic-lichterman-543e8f

@@ -0,0 +1 @@
+Subproject commit b7ec781f7a60cbe48df1478fa4240a926103dbee

.claude/worktrees/great-mclaren-6c9e7b

@@ -0,0 +1 @@
+Subproject commit b7ec781f7a60cbe48df1478fa4240a926103dbee

docs/local-server-sync-plan.md

@@ -0,0 +1,390 @@
+# Local Server Sync Plan
+
+This plan adds a CLI workflow for pulling database and uploads from a Vantage application into the local Altis codebase where the command is run.
+
+## Goal
+
+Provide a safe, repeatable local sync command:
+
+```sh
+altis-cli app sync all <app>
+altis-cli app sync database <app>
+altis-cli app sync uploads <app>
+```
+
+This command is expected to be run from a local Altis project that uses `altis/local-server`. This is different from Vantage's app-to-app import endpoints. Local sync should use Vantage exports/backups, download the archive locally, and restore it into the current local-server project.
+
+## Adjacent Repo Changes
+
+### `../hm/vantage-backend`
+
+No required changes for the first implementation.
+
+Existing API support is enough:
+
+- `POST /stack/applications/{stack}/backups`
+- `GET /stack/applications/{stack}/backups`
+- Existing stream-log support through `/stream-log`
+- Existing search-replace configuration convention in `extra.altis.cloud.search-replace`
+
+The backup archive already contains:
+
+```txt
+database.sql.gz
+uploads/
+```
+
+Optional future improvement:
+
+- Return the generated backup object ID or download URL from the backup task/log metadata after completion. This would remove the need for the CLI to list backups and select the newest matching backup after a streamed export completes.
+- Add a small endpoint that exposes the resolved search-replace mappings for an application/build using the same logic as Vantage's app-to-app import flow. This is not required for the first CLI implementation if the CLI reads mappings from the local project's `composer.json`, but it would improve parity with the backend's exact deployed-build resolution.
+
+### `../hm/altis-local-server`
+
+No required changes for the first implementation.
+
+Existing Local Server commands are enough:
+
+- `composer server cli -- db import <file>`
+- `composer server s3 import-uploads`
+- `composer server import-uploads` as an alias in current local-server
+- `composer server status` for a lightweight readiness check
+
+Optional future improvement:
+
+- Add a dedicated `composer server sync-from-archive <archive>` command that imports DB and uploads from a Vantage backup archive in one local-server-native step. This is not needed for the CLI feature because the CLI can orchestrate existing commands.
+
+## New CLI Command Family
+
+Use a nested `app sync` command family.
+
+Commands:
+
+```sh
+altis-cli app sync all <app>
+altis-cli app sync database <app>
+altis-cli app sync uploads <app>
+```
+
+The legacy `stack sync` alias should work too, but docs should prefer `app sync`.
+
+Options:
+
+- `--path <path>`: optional local Altis project path override. Defaults to the current working directory.
+- `--tables <table1,table2>`: database-only table selection.
+- `--uploads-path <prefix>`: uploads prefix to export from remote app.
+- `--search-replace-key <key>`: read mappings from `extra.altis.cloud.search-replace.<key>` in the local project's `composer.json`. Defaults to `local-server`.
+- `--replace <from=to>`: explicit search-replace mapping. Repeatable.
+- `--skip-search-replace`: skip search-replace entirely.
+- `--skip-post-sync`: skip the `wp altis post-sync` hook after database import.
+- `--dry-run-search-replace`: print the resolved mappings that would be applied, without triggering a backup or import.
+- `--output-dir <path>`: working directory for downloaded archives and extracted files. Defaults to a temp directory.
+- `--keep-archive`: keep downloaded `.tar` and extracted files after restore.
+- `--yes`: skip destructive confirmations.
+- `--resume <log-id>`: resume watching an already-started remote backup task.
+- `--debug`: pass through to stream-log rendering.
+- `--json`: print machine-readable summary at the end.
+
+## Workflow
+
+### 1. Validate Local Project
+
+Before calling Vantage:
+
+- Resolve the local project path from `--path` or `process.cwd()`.
+- Check `<local-project>/composer.json` exists.
+- Check the Composer project requires `altis/local-server` in `require` or `require-dev`.
+- Check `<local-project>/content` exists.
+- Check `composer` is available.
+- Run `composer server status` in the local project path. If it fails, show a clear message asking the user to start local-server with `composer server start`.
+
+Do not start local-server automatically in the first implementation. The expected workflow is that the user runs this command from the intended local Altis project after local-server is already set up and running.
+
+### 2. Confirm Destructive Actions
+
+Prompt unless `--yes` is passed.
+
+For database:
+
+```txt
+This will replace the local database for the current Altis project with data from <app>. Continue?
+```
+
+For uploads:
+
+```txt
+This will merge remote uploads from <app> into ./content/uploads. Existing files may be overwritten. Continue?
+```
+
+For `all`, show both warnings in one confirmation.
+
+### 3. Create Remote Export
+
+Call the existing backup endpoint with `stream=true`.
+
+For database:
+
+```http
+POST /stack/applications/{stack}/backups?stream=true
+```
+
+Body/query params:
+
+```json
+{
+  "database": true,
+  "uploads": false,
+  "tables": ["wp_posts", "wp_options"]
+}
+```
+
+For uploads:
+
+```json
+{
+  "database": false,
+  "uploads": true,
+  "uploads_path": "sites/2"
+}
+```
+
+For all:
+
+```json
+{
+  "database": true,
+  "uploads": true
+}
+```
+
+The streamed backup endpoint returns a plain text log ID. Use the existing `streamLog(v, stack, logId, debug)` pattern to show progress.
+
+Implementation note: the current `streamLog()` helper renders progress but does not expose a promise that resolves on completion. `app sync` needs to know when the backup has completed before listing and downloading backups, so either:
+
+- update `streamLog()` to return a promise while preserving existing behavior for current callers, or
+- add a new local helper for `app sync` that uses `v.getLogStream({ id: stack, log: logId })` and resolves on `complete`, rejects on `fail`, and still renders progress.
+
+### 4. Find The Completed Backup
+
+After the stream completes successfully:
+
+- Call `GET /stack/applications/{stack}/backups`.
+- Sort newest first by `date`.
+- Select the newest backup created after the local command start time.
+- Prefer matching the expected manifest shape if available through the listed backup metadata.
+
+If no matching backup is found, print a clear manual recovery message:
+
+```txt
+Backup completed but the CLI could not find the download URL. Run:
+  altis-cli app backups <app>
+```
+
+### 5. Download And Extract
+
+Download the backup `url` to:
+
+```txt
+<output-dir>/<app>-<timestamp>.tar
+```
+
+Extract into:
+
+```txt
+<output-dir>/<app>-<timestamp>/
+```
+
+Expected extracted files:
+
+```txt
+database.sql.gz
+uploads/
+```
+
+Validation:
+
+- If database sync was requested, require `database.sql.gz`.
+- If uploads sync was requested, require `uploads/`.
+
+### 6. Search-Replace And Restore Database
+
+Search-replace runs on the SQL stream before import using `@automattic/vip-search-replace`, which wraps [`go-search-replace`](https://github.com/Automattic/go-search-replace). The binary is downloaded on demand to `~/.altis-cli/bin/go-search-replace` on first use.
+
+Resolve mappings in this order:
+
+1. If `--skip-search-replace` is passed, skip search-replace and go straight to import.
+2. Read config mappings from `extra.altis.cloud.search-replace.local-server` in the local project's `composer.json`. Use `--search-replace-key <key>` to read a different key instead.
+3. Merge repeatable `--replace <from=to>` mappings after config mappings so explicit CLI values can add or override.
+4. Validate every mapping has a non-empty `from` and `to` before running.
+
+Configure local mappings in `composer.json`:
+
+```json
+{
+  "extra": {
+    "altis": {
+      "cloud": {
+        "search-replace": {
+          "local-server": {
+            "example.com": "example.altis.dev",
+            "www.example.com": "example.altis.dev"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+If no mappings are found, continue and print:
+
+```txt
+No search-replace mappings found. Skipping. Use --replace or configure extra.altis.cloud.search-replace.local-server in composer.json.
+```
+
+Pipe the decompressed SQL through `go-search-replace` with all pairs in a single invocation, then feed the replaced stream directly into the local-server DB import:
+
+```js
+const { replace } = require('@automattic/vip-search-replace');
+const replacements = Object.entries( mappings ).flat(); // ['from1','to1','from2','to2',...]
+const sqlStream = fs.createReadStream( sqlGzPath ).pipe( createGunzip() );
+const replacedStream = await replace( sqlStream, replacements );
+// pipe replacedStream into: composer server cli -- db import /dev/stdin
+```
+
+After successful import, always run:
+
+```sh
+composer server cli -- cache flush
+```
+
+Then, unless `--skip-post-sync` is passed, run the Altis post-sync hook to allow the user codebase to perform any environment-specific setup:
+
+```sh
+composer server cli -- altis post-sync
+```
+
+If the command is not found or exits non-zero, print a warning but do not fail the sync.
+
+### 7. Restore Uploads Into Local Server
+
+Extract the backup's `uploads/` directory directly into `<local-project>/content/uploads/` using Node's tar extraction (no rsync needed).
+
+Then run from `<local-project>`:
+
+```sh
+composer server s3 import-uploads
+```
+
+This mounts `content/uploads/` and syncs it into the local S3 container. Fallback for older local-server versions:
+
+```sh
+composer server import-uploads
+```
+
+Try `composer server s3 import-uploads` first, then fall back to `composer server import-uploads` if the first command fails with an unsupported command error.
+
+### 8. Cleanup
+
+Unless `--keep-archive` is passed:
+
+- Remove downloaded archive.
+- Remove extracted working directory.
+
+Keep files on failure and print their paths for debugging.
+
+## Output
+
+Human output should show:
+
+- local project path
+- remote app
+- backup log id
+- downloaded archive path
+- database import status
+- search-replace status and mapping count
+- post-sync hook status
+- uploads import status
+- cleanup status
+
+`--json` should print:
+
+```json
+{
+  "stack": "example-dev-01",
+  "path": "/path/to/local-project",
+  "backup": {
+    "id": "example-dev-01-2026-04-30-12-00-00.tar",
+    "log": "example-dev-01/backups:..."
+  },
+  "database": {
+    "requested": true,
+    "imported": true,
+    "searchReplace": {
+      "requested": true,
+      "ran": true,
+      "dryRun": false,
+      "mappingCount": 2
+    },
+    "postSync": {
+      "ran": true,
+      "exitCode": 0
+    }
+  },
+  "uploads": {
+    "requested": true,
+    "imported": true
+  }
+}
+```
+
+## Safety Rules
+
+- Never delete local uploads by default; merge and overwrite matching files only.
+- Never import database without confirmation unless `--yes` is passed.
+- Never run search-replace unless database sync was requested.
+- Never infer search-replace mappings from stack names, URLs, or local domains. Use composer.json mappings or explicit `--replace` values only.
+- Never infer the local project from a parent directory if `composer.json` is missing in `--path` or `cwd`.
+- Keep failed downloads/extractions for debugging.
+- Do not print signed backup URLs in normal output unless `--debug` is passed.
+
+## Implementation Notes
+
+- This command needs to run local shell commands. Use `child_process.spawn` with argument arrays rather than shell strings.
+- Run local commands with `cwd` set to the local project path.
+- Use Node's temp directory APIs for default `--output-dir`.
+- Use the existing Vantage auth flow and `Vantage.fetch()`.
+- Use existing `streamLog()` for remote backup progress.
+- Use the existing backup download approach from `lib/commands/stack/backups.js` as the starting point for progress reporting.
+- Parse `composer.json` with `JSON.parse()` and resolve `extra.altis.cloud.search-replace.local-server` as structured data.
+- Validate every search-replace mapping has a non-empty string `from` and `to` before running.
+- Use `@automattic/vip-search-replace` for search-replace. It wraps `go-search-replace` and downloads the binary on demand. Pass all pairs as a flat alternating array: `['from1','to1','from2','to2']`. All pairs run in a single invocation.
+- Search-replace runs on the decompressed SQL stream before DB import — no WP-CLI search-replace needed.
+
+## Acceptance Criteria
+
+- `app sync database <app>` creates a remote DB-only backup, downloads it, runs search-replace on the SQL stream, imports it into local-server, and flushes the object cache.
+- `app sync database <app>` reads search-replace mappings from `extra.altis.cloud.search-replace.local-server` in the local project's `composer.json` by default.
+- `app sync database <app>` supports repeatable `--replace <from=to>` mappings that add to or override composer.json mappings.
+- `app sync database <app> --search-replace-key <key>` reads `extra.altis.cloud.search-replace.<key>` instead of `local-server`.
+- `app sync database <app> --skip-search-replace` skips the search-replace step.
+- `app sync database <app>` runs `wp altis post-sync` after import and cache flush by default.
+- `app sync database <app> --skip-post-sync` skips the post-sync hook.
+- A non-zero exit from `wp altis post-sync` prints a warning but does not fail the sync.
+- `app sync database <app> --dry-run-search-replace` prints resolved mappings without triggering a backup or import.
+- `app sync uploads <app>` creates a remote uploads-only backup, downloads it, merges uploads into `content/uploads`, and imports them into local-server S3.
+- `app sync all <app>` performs both restore steps from one remote backup archive.
+- Running from a local Altis project works without passing `--path`.
+- `--path` can still target a local project outside the current working directory when needed.
+- Missing local-server dependency fails before any remote backup starts.
+- Local-server not running fails before any remote backup starts.
+- Destructive actions prompt unless `--yes` is passed.
+- Failed restore keeps the archive/extracted files and prints their paths.
+
+## Follow-Up Features
+
+- Automatic local-server startup with `--start`.
+- Interactive picker for recent backups instead of creating a new backup.
+- Direct download of an existing backup ID.
+- Better matching between streamed backup log ID and completed backup URL if Vantage adds that metadata.
+- Backend endpoint for resolved search-replace mappings from the deployed build, if exact Vantage backend parity becomes more important than local composer.json resolution.