Add sync-ready gate, default protocol/domain, update docs with benchmark findings

- Sync-ready gate: containers wait for Mutagen sync via marker file,
  no more while-loop workarounds needed in commands
- Default routing.protocol to http when port is set
- Default domain to {name}.{scdev_domain} when not set
- Update all docs: .pnpm-store must be in mutagen ignore (prevents
  platform-specific native binaries syncing between glibc/musl)
- Update examples to use pnpm and node:22-alpine throughout
- Update benchmark numbers with true cold start measurements
- Remove node_modules named volume pattern from recommendations
  (mutagen ignore is the correct approach)

Author: ThomasLohner

CLAUDE.md

@@ -53,9 +53,11 @@ When adding a new shared service (easy to miss steps):
 
 ## Gotchas
 
-- Mutagen ignored paths are NOT synced in either direction. This breaks IDE autocomplete if `vendor/` or `node_modules/` are ignored.
+- Mutagen ignored paths are NOT synced in either direction. `node_modules` and `.pnpm-store` should always be ignored for Node.js projects - they stay inside the container for native speed. IDE autocomplete still works because `pnpm install` also runs on the host (or the IDE uses the host's own node_modules).
+- For pnpm projects, `.pnpm-store` MUST be in the mutagen ignore list. pnpm creates a ~500MB content-addressable store inside the project dir when running in a container. Without ignoring it, platform-specific native binaries (glibc vs musl) sync to the host and break when the container image changes.
 - Only directory bind mounts are synced via Mutagen. Single-file mounts stay as regular bind mounts.
 - The docs page (`docs.shared.<domain>`) doubles as a 404 catch-all via Traefik - unmatched URLs redirect there.
+- The sync-ready gate (`/.scdev-sync-ready` marker) automatically holds the container's command until Mutagen sync completes. No need for `while [ ! -f ... ]` workarounds in commands.
 
 ## README
 

README.md

@@ -75,13 +75,19 @@ name: my-app
 
 services:
   app:
-    image: node:20-alpine
-    command: npm run dev
+    image: node:22-alpine
+    command: corepack enable && pnpm install && pnpm dev --host 0.0.0.0
     working_dir: /app
     volumes:
-      - ${PROJECTPATH}:/app    # mounts your project directory into the container
+      - ${PROJECTPATH}:/app
     routing:
       port: 3000
+
+mutagen:
+  ignore:
+    - node_modules
+    - .pnpm-store
+    - .nuxt
 ```
 
 `${PROJECTPATH}` is resolved automatically to your project's absolute path. Other available variables: `${PROJECTNAME}`, `${PROJECTDIR}`, `${SCDEV_DOMAIN}`.
@@ -124,25 +130,30 @@ Every project and shared service gets locally-trusted HTTPS certificates. Your b
 
 File sharing between your host and containers is notoriously slow on macOS. scdev automatically syncs files at native speed - no configuration needed. On Linux this isn't needed (already fast).
 
-How much difference does it make? We benchmarked `pnpm install` on a Nuxt app:
+How much difference does it make? We benchmarked a Nuxt 4 app with ~1000 dependencies:
 
-| Approach | pnpm install | Dev server ready |
-|----------|-------------|-----------------|
-| Docker bind mount (default macOS) | **34.6s** | 7s |
-| scdev with file sync | **4.9s** | 4s |
+| Approach | pnpm install | Cold start to app ready |
+|----------|-------------|------------------------|
+| Docker bind mount (default macOS) | **34.6s** | ~42s |
+| scdev with file sync | **6.7s** | ~17s |
+| scdev warm restart (stop + start) | **2.4s** | ~2s |
 
-That's a **7x speedup** on dependency installation. The trick: scdev syncs your source code via fast file sync, while keeping `node_modules` inside the container where filesystem operations are native speed.
+That's a **5x speedup** on cold start and **instant** warm restarts. The trick: scdev syncs your source code via fast file sync, while keeping `node_modules` and other generated files inside the container where filesystem operations are native speed.
 
-Exclude paths you don't need synced:
+Exclude paths you don't need synced back to the host:
 
 ```yaml
 mutagen:
   ignore:
     - node_modules
+    - .pnpm-store    # pnpm's content-addressable store - platform-specific, don't sync
     - .nuxt
+    - .output
     - var/cache
 ```
 
+**Important:** Always add `.pnpm-store` to the ignore list for pnpm projects. pnpm creates its package store inside the project directory when running in a container. Without ignoring it, ~500MB of platform-specific binaries sync to the host, causing slow syncs and broken native modules when switching images.
+
 ### TCP/UDP Routing
 
 Beyond HTTPS, scdev can expose raw TCP and UDP ports. This lets you connect to a database inside a project from your host using tools like DBeaver, pgAdmin, or `psql`:
@@ -167,18 +178,18 @@ Multiple projects can expose different ports without conflicts. Works for MySQL,
 
 ### Volumes
 
-**Bind mounts** (`${PROJECTPATH}:/app`) sync your source code into the container. Edits on the host are reflected immediately. On macOS, scdev handles fast sync automatically.
+**Bind mounts** (`${PROJECTPATH}:/app`) sync your source code into the container. Edits on the host are reflected immediately. On macOS, scdev handles fast sync automatically via Mutagen. Add `node_modules`, `.pnpm-store`, and build caches to `mutagen.ignore` so they stay inside the container (fast) and don't sync back to the host.
 
-**Named volumes** (`node_modules:/app/node_modules`) are persistent storage managed by scdev. Use these for dependencies, database files, and caches - things that are huge, change constantly, and would kill sync performance:
+**Named volumes** (`db_data:/var/lib/postgresql/data`) are persistent storage managed by scdev. Use these for data that must survive `scdev down` - database files, uploaded assets, SQLite databases:
 
 ```yaml
 volumes:
   - ${PROJECTPATH}:/app              # your source code (synced to host)
-  - node_modules:/app/node_modules   # dependencies (stays in container, fast)
-  - db_data:/var/lib/postgresql/data  # database files (persists across restarts)
+  - db_data:/var/lib/postgresql/data  # database files (persists across down)
+  - data:/app/data                   # SQLite, uploads, etc.
 ```
 
-Named volumes persist across `scdev stop`/`scdev start` and are removed with `scdev down -v`. No separate declaration needed - scdev discovers them automatically.
+Named volumes persist across `scdev stop`/`scdev start` AND `scdev down`. Only removed with `scdev down -v`. No separate declaration needed - scdev discovers them automatically.
 
 ### Custom Commands
 
@@ -194,15 +205,15 @@ Every project has recurring tasks: install deps, run migrations, seed data, run
 ```bash
 # .scdev/commands/setup.just
 default:
-    scdev exec app npm ci
+    scdev exec app pnpm ci
     scdev exec app npx prisma db push
 
 # .scdev/commands/test.just
 default:
-    scdev exec app npm test
+    scdev exec app pnpm test
 
 watch:
-    scdev exec app npm test -- --watch
+    scdev exec app pnpm test -- --watch
 ```
 
 ```bash
@@ -233,7 +244,7 @@ scdev down -v     # Remove everything including volumes
 
 ```bash
 scdev exec app bash              # Shell into a container
-scdev exec app npm test          # Run a command
+scdev exec app pnpm test         # Run a command
 scdev logs                       # View logs
 scdev logs -f app                # Follow logs for a service
 ```
@@ -299,12 +310,11 @@ name: my-api
 
 services:
   app:
-    image: node:20-alpine
-    command: npm run dev
+    image: node:22-alpine
+    command: corepack enable && pnpm install && pnpm dev --host 0.0.0.0
     working_dir: /app
     volumes:
       - ${PROJECTPATH}:/app
-      - node_modules:/app/node_modules
     environment:
       DATABASE_URL: postgres://postgres:postgres@db:5432/app
     routing:
@@ -317,6 +327,12 @@ services:
     environment:
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: app
+
+mutagen:
+  ignore:
+    - node_modules
+    - .pnpm-store
+    - .nuxt
 ```
 
 ### Static Site / Frontend
@@ -326,13 +342,18 @@ name: my-docs
 
 services:
   app:
-    image: node:20-alpine
-    command: npm run dev
+    image: node:22-alpine
+    command: corepack enable && pnpm install && pnpm dev --host 0.0.0.0
     working_dir: /app
     volumes:
       - ${PROJECTPATH}:/app
     routing:
       port: 5173
+
+mutagen:
+  ignore:
+    - node_modules
+    - .pnpm-store
 ```
 
 ## Configuration Reference
@@ -344,13 +365,18 @@ name: my-app
 
 services:
   app:
-    image: node:20-alpine
-    command: npm run dev
+    image: node:22-alpine
+    command: corepack enable && pnpm install && pnpm dev --host 0.0.0.0
     working_dir: /app
     volumes:
       - ${PROJECTPATH}:/app
     routing:
       port: 3000
+
+mutagen:
+  ignore:
+    - node_modules
+    - .pnpm-store
 ```
 
 ### Full config with all options

internal/config/loader.go

@@ -77,6 +77,19 @@ func LoadProject(projectDir string) (*ProjectConfig, error) {
 		cfg.Name = projectName
 	}
 
+	// Default domain to {name}.{scdev_domain}
+	if cfg.Domain == "" {
+		cfg.Domain = cfg.Name + "." + DefaultDomain
+	}
+
+	// Default routing protocol to "http" when port is set
+	for name, svc := range cfg.Services {
+		if svc.Routing != nil && svc.Routing.Port != 0 && svc.Routing.Protocol == "" {
+			svc.Routing.Protocol = "http"
+			cfg.Services[name] = svc
+		}
+	}
+
 	return &cfg, nil
 }
 

internal/project/mutagen_sync.go

@@ -294,3 +294,16 @@ func (p *Project) transformVolumesForMutagen(serviceName string, volumes []strin
 
 	return result
 }
+
+// signalSyncReady writes a marker file into each container that has a Mutagen sync mount,
+// unblocking the sync-ready gate in the container's entrypoint wrapper.
+func (p *Project) signalSyncReady(ctx context.Context, mounts []MutagenSyncMount) {
+	for _, mount := range mounts {
+		containerName := p.ContainerName(mount.ServiceName)
+		err := p.Runtime.Exec(ctx, containerName,
+			[]string{"sh", "-c", "touch /.scdev-sync-ready"}, false, runtime.ExecOptions{})
+		if err != nil {
+			fmt.Printf("Warning: could not signal sync-ready for %s: %v\n", mount.ServiceName, err)
+		}
+	}
+}

internal/project/project.go

@@ -64,6 +64,11 @@ func (p *Project) NetworkName() string {
 	return fmt.Sprintf("%s.scdev", p.Config.Name)
 }
 
+// shellQuote wraps a string in single quotes, escaping any embedded single quotes.
+func shellQuote(s string) string {
+	return "'" + strings.ReplaceAll(s, "'", "'\\''") + "'"
+}
+
 // VolumeName returns the full volume name for a project volume
 // Format: <volume>.<project>.scdev (e.g., db_data.myproject.scdev)
 func (p *Project) VolumeName(volume string) string {
@@ -282,6 +287,9 @@ func (p *Project) Start(ctx context.Context) error {
 
 		// Wait for initial sync (60 second timeout)
 		p.waitForInitialSync(ctx, m, mutagenMounts, 60*time.Second)
+
+		// Signal containers that sync is ready (unblocks the sync-ready gate)
+		p.signalSyncReady(ctx, mutagenMounts)
 	}
 
 	// Register project with routing info in state
@@ -404,7 +412,17 @@ func (p *Project) startServiceWithMutagen(ctx context.Context, name string, svc
 
 	// Parse command if specified
 	if svc.Command != "" {
-		cfg.Command = []string{"sh", "-c", svc.Command}
+		// When Mutagen is enabled for this service, wrap the command with a sync-ready gate.
+		// Files arrive via sync AFTER the container starts, so the command would fail immediately
+		// without this gate. The marker file is written by signalSyncReady() after initial sync.
+		_, hasMutagenMount := mutagenMounts[name]
+		if mutagenEnabled && hasMutagenMount {
+			cfg.Command = []string{"sh", "-c",
+				"while [ ! -f /.scdev-sync-ready ]; do sleep 0.2; done; exec sh -c " + shellQuote(svc.Command),
+			}
+		} else {
+			cfg.Command = []string{"sh", "-c", svc.Command}
+		}
 	}
 
 	// Create and start