primo-cli 0.1.18 → 0.1.20

package/dist/commands/deploy.js

@@ -479,18 +479,26 @@ async function wait_for_ready(url) {
 // Run the equivalent of `primo push` against the local workspace. push_site
 // resolves the server URL from server.yaml (which we just wrote), so no extra
 // flags are needed. We surface failures but don't re-throw — the deploy already
-// succeeded and the user can rerun push manually.
+// succeeded and the user can rerun push manually. Only a fully clean push
+// counts as success: a partial upload must not be reported as "complete".
 async function run_auto_push(inventory) {
     console.log('');
     console.log(chalk.cyan('Uploading your workspace...'));
     try {
-        await push_site({ dir: inventory.root_dir });
+        const failed = await push_site({ dir: inventory.root_dir });
+        if (failed.length > 0) {
+            // push_site already printed the per-item errors, the summary, and
+            // set the exit code. The server itself is fine, so finish the
+            // deploy flow — just not as "complete".
+            return false;
+        }
         return true;
     }
     catch (error) {
         console.log('');
         console.log(chalk.yellow(`Auto-push failed: ${error instanceof Error ? error.message : error}`));
         console.log(chalk.dim('  Your server is live — rerun `primo push` once the issue is sorted.'));
+        process.exitCode = 1;
         return false;
     }
 }

package/dist/commands/dev.js

@@ -131,21 +131,73 @@ function compute_shrink_delta(prior, next) {
     const delta = next_lines - prior_lines;
     return delta < 0 ? delta : null;
 }
-// Write the most recent push outcome to a file the MCP build_preview tool
-// reads, so the agent learns when its file changes failed to land in the CMS.
-// Without this, build_preview compiles whatever stale DB state existed before
-// the failed push and reports ok:true, leaving the agent to chase phantom
-// rendering bugs instead of fixing the source error.
-async function write_sync_status(site_dir, status) {
+// Write the most recent push outcome to a file the MCP build_preview and
+// get_dev_status tools read, so the agent learns when its file changes failed
+// to land in the CMS and exactly which fields were dropped. Without this,
+// build_preview compiles whatever stale DB state existed before the failed
+// push and reports ok:true, leaving the agent to chase phantom rendering bugs
+// instead of fixing the source error.
+async function write_sync_status(site_dir, status, location = {}) {
     const status_dir = path.join(site_dir, '.primo');
     try {
         await fs.mkdir(status_dir, { recursive: true });
-        await fs.writeFile(path.join(status_dir, 'sync_status.json'), JSON.stringify(status, null, 2));
+        // last_import_at stamps every write so a reader can tell a fresh status
+        // from a stale one; port/url tell the agent where the server is.
+        const payload = {
+            ...status,
+            ...(location.port !== undefined ? { port: location.port } : {}),
+            ...(location.url !== undefined ? { url: location.url } : {}),
+            last_import_at: new Date().toISOString()
+        };
+        // Write atomically: a plain fs.writeFile truncates-then-writes, so the
+        // MCP get_dev_status reader can catch a half-written file and briefly
+        // report "not running" mid-write. Write to a temp file in the same dir
+        // (same filesystem → rename is atomic on POSIX) and rename over the
+        // target, so readers always see a complete old or new file.
+        const target = path.join(status_dir, 'sync_status.json');
+        const tmp = path.join(status_dir, `sync_status.${process.pid}.${randomInt(1e9)}.tmp`);
+        try {
+            await fs.writeFile(tmp, JSON.stringify(payload, null, 2));
+            await fs.rename(tmp, target);
+        }
+        catch (err) {
+            await fs.unlink(tmp).catch(() => { });
+            throw err;
+        }
     }
     catch {
         // Status reporting must not break the push.
     }
 }
+// Persist a successful import's outcome to sync_status.json — with the full
+// per-field warning details when content was dropped, so an agent can read
+// exactly what was lost without re-running dev. Shared by the boot loop and
+// the file watcher so both readers of the file see the same shape.
+async function write_import_sync_status(site_dir, import_timings, location) {
+    // The bootstrap+import fallback can return timings even when nothing
+    // imported (both attempts failed and were only logged). Never record a
+    // phantom success for that — write ok:false so the agent doesn't build a
+    // preview from unchanged CMS state.
+    if (!import_timings.ok) {
+        await write_sync_status(site_dir, {
+            ok: false,
+            error: 'Import failed — see the primo dev logs for details.',
+            failed_at: new Date().toISOString()
+        }, location);
+        return;
+    }
+    if (import_timings.warning_count > 0) {
+        await write_sync_status(site_dir, {
+            ok: true,
+            warnings: import_timings.warning_count,
+            warned_at: new Date().toISOString(),
+            warning_details: import_timings.warning_details
+        }, location);
+    }
+    else {
+        await write_sync_status(site_dir, { ok: true }, location);
+    }
+}
 async function prune_old_trash(workspace_dir) {
     const trash_dir = path.join(workspace_dir, '.primo', 'trash');
     try {
@@ -607,6 +659,9 @@ export async function dev_server(options) {
             process.exit(1);
         }
         const api_url = `http://127.0.0.1:${port}`;
+        // Stamped into every sync_status.json write so an agent reading the
+        // file also learns where the running server is.
+        const dev_location = { port, url: api_url };
         if (is_server_mode) {
             spinner.text = sync_policy.mode === 'cms' ? 'Pulling shared library...' : 'Loading shared library...';
             is_importing_library = true;
@@ -625,6 +680,7 @@ export async function dev_server(options) {
         // Normalize and load all sites
         spinner.text = `Loading ${sites.length} site${sites.length > 1 ? 's' : ''}...`;
         const blocked_sites = new Set();
+        let dropped_field_count = 0;
         for (const site of sites) {
             const use_bootstrap = !await site_exists(api_url, site.config.site_id);
             if (sync_policy.mode === 'cms' && !use_bootstrap) {
@@ -642,7 +698,21 @@ export async function dev_server(options) {
                 blocked_site_keys.add(site_key);
                 continue;
             }
+            // Write sync_status.json on boot too — otherwise an agent reading
+            // right after `primo dev` starts sees stale/absent state, and any
+            // dropped fields from the initial import stay invisible until the
+            // next file save. Writes ok:false when the import didn't land.
+            await write_import_sync_status(site.dir, import_timings, dev_location);
+            if (!import_timings.ok) {
+                // Bootstrap and its regular-import fallback both failed (only
+                // logged, not thrown). Keep the site quarantined and skip the
+                // baseline/success path so we don't record a phantom import.
+                blocked_sites.add(site.dir);
+                blocked_site_keys.add(site_key);
+                continue;
+            }
             blocked_site_keys.delete(site_key);
+            dropped_field_count += import_timings.dropped_field_count;
             if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
                 await update_site_sync_baseline(site, api_url, server_config, base_dir);
             }
@@ -655,6 +725,15 @@ export async function dev_server(options) {
             await verify_site_ready(api_url, site.config.site_id);
         }
         spinner.succeed('Primo running');
+        // Restate any dropped-field warnings next to the banner. The per-field
+        // detail already printed above during import, but on a multi-site or
+        // long boot it scrolls out of view and the green banner reads as
+        // "all good" — so surface the aggregate here as the last thing on
+        // screen. See print_import_warnings for the full per-field output.
+        if (dropped_field_count > 0) {
+            console.log('');
+            console.log(chalk.yellow(`  ⚠ ${dropped_field_count} field${dropped_field_count === 1 ? '' : 's'} dropped — content not imported (see warnings above)`));
+        }
         console.log('');
         if (mcp_registration_path) {
             console.log(`  ${chalk.dim(`MCP server registered at ${mcp_registration_path} - agents in this directory can now use the Primo MCP server.`)}`);
@@ -834,7 +913,18 @@ export async function dev_server(options) {
                                 // Conflict detection must not block the local push.
                             }
                         }
-                        const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, false, base_dir));
+                        // Steady-state pushes go through the additive import
+                        // endpoint (use_bootstrap=false). But a site whose initial
+                        // bootstrap+fallback both failed is quarantined and was
+                        // never created on the server — retrying import against a
+                        // nonexistent site would fail forever. For those, re-check
+                        // existence so the retry can bootstrap out of quarantine.
+                        // Healthy sites are never quarantined, so they skip the
+                        // extra request and keep the fast path.
+                        const retry_needs_bootstrap = blocked_site_keys.has(get_site_sync_key(site.dir, site.config))
+                            ? !await site_exists(api_url, site.config.site_id)
+                            : false;
+                        const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, retry_needs_bootstrap, base_dir));
                         if (import_timings === null) {
                             // Duplicate _ids — import_site_files already printed the
                             // error and wrote sync_status; nothing was pushed. Keep
@@ -869,16 +959,7 @@ export async function dev_server(options) {
                         }
                         console.log(chalk.dim(`  ${site.config.name}: normalize ${normalize_ms}ms, zip ${import_timings.zip_ms}ms, ${import_timings.mode} ${import_timings.request_ms}ms${reload_ms ? `, reload ${reload_ms}ms` : ''}`));
                         console.log(chalk.green(`  ✓ ${site.config.name} pushed`));
-                        if (import_timings.warning_count > 0) {
-                            await write_sync_status(site.dir, {
-                                ok: true,
-                                warnings: import_timings.warning_count,
-                                warned_at: new Date().toISOString()
-                            });
-                        }
-                        else {
-                            await write_sync_status(site.dir, { ok: true });
-                        }
+                        await write_import_sync_status(site.dir, import_timings, dev_location);
                     }
                     catch (err) {
                         const message = err instanceof Error ? err.message : String(err);
@@ -887,7 +968,7 @@ export async function dev_server(options) {
                             ok: false,
                             error: message,
                             failed_at: new Date().toISOString()
-                        });
+                        }, dev_location);
                     }
                     finally {
                         is_importing = false;
@@ -990,12 +1071,15 @@ export async function dev_server(options) {
                     return;
                 }
                 const new_sites = await discover_sites(base_dir);
+                let loaded_count = 0;
+                const quarantined = [];
                 for (const site of new_sites) {
                     if (known_sites.has(site.dir))
                         continue;
                     known_sites.add(site.dir);
                     sites.push(site);
                     const use_bootstrap = !await site_exists(api_url, site.config.site_id);
+                    let import_ok = true;
                     if (sync_policy.mode === 'cms' && !use_bootstrap) {
                         await sync_from_cms(site.dir, api_url, site.config, server_config, base_dir, sync_policy);
                     }
@@ -1006,19 +1090,46 @@ export async function dev_server(options) {
                             // Duplicate _ids on a freshly discovered site — quarantine
                             // it from CMS→file polling until a later import succeeds.
                             blocked_site_keys.add(get_site_sync_key(site.dir, site.config));
+                            quarantined.push(site.config.name);
+                            import_ok = false;
                         }
-                        else if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
-                            await update_site_sync_baseline(site, api_url, server_config, base_dir);
+                        else {
+                            await write_import_sync_status(site.dir, import_timings, dev_location);
+                            if (!import_timings.ok) {
+                                // Bootstrap + fallback both failed (only logged). Quarantine
+                                // and skip the success path so we don't announce a site that
+                                // didn't actually load — and so `primo new` sees it in the
+                                // /reload body's `quarantined` list.
+                                blocked_site_keys.add(get_site_sync_key(site.dir, site.config));
+                                quarantined.push(site.config.name);
+                                import_ok = false;
+                            }
+                            else if (update_site_sync_state_after_import(site, import_timings, sync_policy)) {
+                                await update_site_sync_baseline(site, api_url, server_config, base_dir);
+                            }
                         }
                     }
                     setup_site_watchers(site);
+                    loaded_count++;
+                    if (!import_ok) {
+                        console.log(chalk.yellow(`  ⚠ ${site.config.name}: import failed — see logs; will retry on the next file change.`));
+                        continue;
+                    }
                     const host = local_dev_host(site.config.name || path.basename(site.dir), port);
                     console.log(chalk.green(`  ✓ New site loaded: ${site.config.name}`));
                     console.log(`    ${chalk.dim('Edit:')}    http://${host}/admin/site`);
                     console.log(`    ${chalk.dim('Preview:')} http://${host}/`);
                 }
-                res.writeHead(200);
-                res.end('ok');
+                // Report the outcome so `primo new` can tell whether the site it
+                // just scaffolded actually imported. A quarantined site (duplicate
+                // _ids) returns 200 with loaded:false so a 2xx no longer implies
+                // success — the caller checks the body, not just the status.
+                const body = JSON.stringify({
+                    loaded: loaded_count,
+                    quarantined
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(body);
             });
             reload_server.on('error', (err) => {
                 if (err.code === 'EADDRINUSE') {
@@ -1868,6 +1979,37 @@ async function prepare_site_for_local_dev(site_dir) {
         warnings
     };
 }
+// Warning kinds where page content was matched to no field and therefore
+// dropped from the render model. Counted separately from other import
+// warnings (unknown blocks, orphan uploads, duplicate ids) so the
+// end-of-boot summary can report "N fields dropped" accurately.
+const DROPPED_FIELD_KINDS = new Set(['orphaned_field', 'orphaned_page_field']);
+// Number of dropped-field warnings in an import response. Safe on any input
+// shape (returns 0 for non-arrays / missing warnings).
+function count_dropped_fields(warnings) {
+    if (!Array.isArray(warnings))
+        return 0;
+    return warnings.filter(w => DROPPED_FIELD_KINDS.has(w.kind)).length;
+}
+// Coerce a raw import-response `warnings` value into a clean ImportWarning[]
+// for persistence in sync_status.json. Defensive against partial/unknown
+// server shapes: drops non-object entries and fills missing string fields so
+// the agent-facing file always has a predictable schema. Returns [] for
+// non-arrays / missing warnings.
+function normalize_warning_details(warnings) {
+    if (!Array.isArray(warnings))
+        return [];
+    return warnings
+        .filter((w) => typeof w === 'object' && w !== null)
+        .map(w => ({
+        kind: typeof w.kind === 'string' ? w.kind : '',
+        file: typeof w.file === 'string' ? w.file : '',
+        path: typeof w.path === 'string' ? w.path : '',
+        field: typeof w.field === 'string' ? w.field : '',
+        block: typeof w.block === 'string' ? w.block : '',
+        message: typeof w.message === 'string' ? w.message : ''
+    }));
+}
 // Loudly surface non-fatal import problems (e.g. orphaned fields whose
 // content would otherwise be silently dropped). Printed in yellow with the
 // full details so agents and humans both see exactly what was lost and where.
@@ -1902,7 +2044,7 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
             ok: false,
             error: message,
             failed_at: new Date().toISOString()
-        });
+        }, { port, url: api_url });
         try {
             // Best-effort — older servers don't have this endpoint.
             await fetch(`${api_url}/api/primo/dev/status`, {
@@ -1939,12 +2081,16 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
         }
         // Write created IDs back to files
         let warning_count = 0;
+        let dropped_field_count = 0;
+        let warning_details = [];
         try {
             const result = await import_response.json();
             if (result.created_ids) {
                 await write_created_ids(site_dir, result.created_ids, server_config, workspace_dir);
             }
             warning_count = print_import_warnings(config.name, result.warnings);
+            dropped_field_count = count_dropped_fields(result.warnings);
+            warning_details = normalize_warning_details(result.warnings);
         }
         catch {
             // ignore JSON parse errors
@@ -1953,7 +2099,10 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
             zip_ms,
             request_ms,
             mode: 'import',
-            warning_count
+            ok: true,
+            warning_count,
+            dropped_field_count,
+            warning_details
         };
     }
     // Retry bootstrap up to 3 times (collections may not be ready immediately)
@@ -1976,6 +2125,8 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
             }, 300000); // 300s timeout for imports
             const bootstrap_ms = Date.now() - bootstrap_started;
             let warning_count = 0;
+            let dropped_field_count = 0;
+            let warning_details = [];
             if (bootstrap_response.ok) {
                 try {
                     const result = await bootstrap_response.json();
@@ -1988,6 +2139,8 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
                         await write_created_ids(site_dir, result.created_ids, server_config, workspace_dir);
                     }
                     warning_count = print_import_warnings(config.name, result.warnings);
+                    dropped_field_count = count_dropped_fields(result.warnings);
+                    warning_details = normalize_warning_details(result.warnings);
                 }
                 catch {
                     // ignore JSON parse errors
@@ -1996,7 +2149,10 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
                     zip_ms,
                     request_ms: bootstrap_ms,
                     mode: 'bootstrap',
-                    warning_count
+                    ok: true,
+                    warning_count,
+                    dropped_field_count,
+                    warning_details
                 };
             }
             const error_text = await bootstrap_response.text();
@@ -2027,6 +2183,8 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
                         await write_created_ids(site_dir, result.created_ids, server_config, workspace_dir);
                     }
                     warning_count = print_import_warnings(config.name, result.warnings);
+                    dropped_field_count = count_dropped_fields(result.warnings);
+                    warning_details = normalize_warning_details(result.warnings);
                 }
                 catch {
                     // ignore JSON parse errors
@@ -2036,7 +2194,14 @@ async function import_site_files(site_dir, api_url, config, port, server_config,
                 zip_ms,
                 request_ms: bootstrap_ms + import_ms,
                 mode: 'bootstrap+import',
-                warning_count
+                // Bootstrap failed and we fell back to a regular import; ok
+                // reflects whether that fallback actually landed. When both
+                // failed we still return timings (only logged above), so this
+                // guards against recording a phantom success.
+                ok: import_response.ok,
+                warning_count,
+                dropped_field_count,
+                warning_details
             };
         }
         catch (err) {

package/dist/commands/new.js

@@ -50,16 +50,20 @@ export async function new_site(options) {
                 name: 'name',
                 message: 'Site name:',
                 default: 'my-site',
-                validate: (input) => {
-                    if (!input.trim())
-                        return 'Name is required';
-                    if (!/^[a-z0-9.-]+$/i.test(input))
-                        return 'Use only letters, numbers, dots, and hyphens';
-                    return true;
-                }
+                validate: validate_site_name
             }]);
         site_name = name;
     }
+    else {
+        // A name passed as a CLI arg skips the prompt — validate it too, or a
+        // name like `.foo` slips through: it makes a hidden sites/.foo dir that
+        // discover_sites ignores, and an empty display_name downstream.
+        const error = validate_site_name(site_name);
+        if (error !== true) {
+            console.log(chalk.red(error));
+            process.exit(1);
+        }
+    }
     // Always create site in sites/<name>
     const site_dir = path.join(sites_dir, site_name);
     // Check if directory exists
@@ -250,20 +254,67 @@ sections:
             await fs.writeFile(workspace_agents_path, generate_agent_md());
         }
         spinner.succeed(`Site created: ${chalk.cyan(site_dir)}`);
-        // Check if server is already running
-        const port = 3000;
+        // Check if server is already running. Read the workspace's configured
+        // port (mirroring `primo dev`, which uses server_config.port) rather than
+        // assuming 3000 — otherwise on a custom-port workspace we'd probe the
+        // wrong port, miss the running server, and print links to a dead port.
+        const port = server_config.port ?? 3000;
         const server_running = await is_server_running(port);
         if (server_running) {
-            // Tell the server to reload and pick up the new site
+            // A `primo dev` is already running. Ask it to reload and pick up the
+            // new site. The dev server prints its own "New site loaded" + links,
+            // but in *its* terminal — so print the same links here too, otherwise
+            // this terminal looks like nothing happened.
+            // Host is derived from the display name (what becomes config.name),
+            // matching how dev_server builds the host — not the raw folder name.
+            const host = local_dev_host(display_name, port);
+            let outcome = 'unreachable';
             try {
-                await fetch(`http://127.0.0.1:${port + 1}/reload`, { method: 'POST' });
+                // Bound the request: the reload handler runs discovery + import
+                // synchronously before responding, so an unbounded fetch could
+                // hang here forever and never reach the warning below.
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 30000);
+                let res;
+                try {
+                    res = await fetch(`http://127.0.0.1:${port + 1}/reload`, {
+                        method: 'POST',
+                        signal: controller.signal
+                    });
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+                if (res.ok) {
+                    // A 2xx no longer implies the site imported — the handler
+                    // returns { quarantined: [...] } for sites it couldn't load
+                    // (duplicate _ids). Parse the body to tell the difference.
+                    const result = await res.json().catch(() => null);
+                    outcome = result?.quarantined?.includes(display_name)
+                        ? 'quarantined'
+                        : 'reloaded';
+                }
             }
             catch {
-                // Reload server might not be running (older version)
+                // Reload server not running (older `primo dev`, hot reload disabled
+                // because the port was in use) or the request timed out. Site files
+                // are on disk; restarting `primo dev` will pick them up.
             }
             console.log('');
-            console.log(chalk.dim(`  http://${site_name}.localhost:${port}/`));
+            console.log(`  ${chalk.cyan(display_name)}`);
+            console.log(`    ${chalk.dim('Edit:')}    http://${host}/admin/site`);
+            console.log(`    ${chalk.dim('Preview:')} http://${host}/`);
             console.log('');
+            if (outcome === 'quarantined') {
+                console.log(chalk.yellow('  Site created, but the dev server couldn\'t import it (duplicate IDs).'));
+                console.log(chalk.dim('  Check the `primo dev` logs and fix the conflict.'));
+                console.log('');
+            }
+            else if (outcome === 'unreachable') {
+                console.log(chalk.yellow('  Couldn\'t reach the running dev server to reload it.'));
+                console.log(chalk.dim('  Restart `primo dev` to pick up the new site.'));
+                console.log('');
+            }
         }
         else if (!options.skipDev) {
             // No server running, start one
@@ -282,6 +333,26 @@ sections:
         process.exit(1);
     }
 }
+// Shared name validation for both the interactive prompt and the CLI arg.
+// Returns `true` when valid, or an error string (inquirer's contract).
+// Leading dots/hyphens are rejected: a leading dot makes a hidden sites/.<name>
+// directory that discover_sites skips, and strips display_name to empty.
+function validate_site_name(input) {
+    if (!input.trim())
+        return 'Name is required';
+    if (!/^[a-z0-9.-]+$/i.test(input))
+        return 'Use only letters, numbers, dots, and hyphens';
+    if (/^[.-]/.test(input))
+        return 'Name can\'t start with a dot or hyphen';
+    return true;
+}
+// Mirror of dev.ts's local_dev_host: slug the display name into a
+// `<slug>.localhost:<port>` host so the links printed here match the ones
+// `primo dev` prints for the same site.
+function local_dev_host(name, port) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'site';
+    return `${slug}.localhost:${port}`;
+}
 function generate_id() {
     const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
     let id = '';

package/dist/commands/push.d.ts

@@ -7,5 +7,5 @@ interface PushOptions {
     preview?: boolean;
     dryRun?: boolean;
 }
-export declare function push_site(options: PushOptions): Promise<void>;
+export declare function push_site(options: PushOptions): Promise<string[]>;
 export {};

package/dist/commands/push.js

@@ -39,6 +39,8 @@ async function resolve_group_name(site_dir, group_id) {
     }
     return undefined;
 }
+// Returns the labels (site slugs / 'library') that failed to push so callers
+// like `primo deploy` can tell a clean run from a partial one. Empty = success.
 export async function push_site(options) {
     const root_dir = path.resolve(options.dir);
     const has_site_yaml = await path_exists(get_site_config_path(root_dir));
@@ -61,17 +63,27 @@ export async function push_site(options) {
         : options;
     if (options.dryRun) {
         await print_push_dry_run(root_dir, has_site_yaml, has_server_yaml, effective_options);
-        return;
+        return [];
     }
     // Server-folder mode: walk site subfolders + push library
     if (!has_site_yaml && has_server_yaml) {
-        await push_server(root_dir, effective_options);
-        return;
+        const failed = await push_server(root_dir, effective_options);
+        if (failed.length > 0) {
+            console.log('');
+            console.log(chalk.red(`Push incomplete — failed: ${failed.join(', ')}`));
+            console.log(chalk.dim('  Fix the errors above and rerun `primo push` (completed pushes are safe to repeat).'));
+            console.log('');
+            // exitCode (not process.exit) so an in-process caller like `primo
+            // deploy` can still finish its own reporting before the process ends.
+            process.exitCode = 1;
+        }
+        return failed;
     }
     // Single-site mode (cwd is a site folder, or --dir points at one)
     const spinner = ora('Reading local files...').start();
     try {
         await push_single_site(root_dir, effective_options, spinner);
+        return [];
     }
     catch (error) {
         spinner.fail(`Push failed: ${error instanceof Error ? error.message : error}`);
@@ -166,6 +178,9 @@ async function print_push_dry_run(root_dir, has_site_yaml, has_server_yaml, opti
     console.log(chalk.dim('  No requests sent. Run without --dry-run to push.'));
     console.log('');
 }
+// Pushes every site folder plus the library, continuing past individual
+// failures. Returns the labels that failed — the caller decides how loudly a
+// partial push should fail.
 async function push_server(root_dir, options) {
     // Sites live under sites/<slug>/
     const sites_root = path.join(root_dir, 'sites');
@@ -204,9 +219,10 @@ async function push_server(root_dir, options) {
                 print_auth_hint();
             process.exit(1);
         }
-        return;
+        return [];
     }
     let saw_auth_error = false;
+    const failed = [];
     // Push each site
     for (const site_dir of site_dirs) {
         const spinner = ora(`Pushing ${chalk.cyan(path.basename(site_dir))}...`).start();
@@ -217,6 +233,7 @@ async function push_server(root_dir, options) {
             spinner.fail(`${path.basename(site_dir)}: ${error instanceof Error ? error.message : error}`);
             if (is_auth_error(error))
                 saw_auth_error = true;
+            failed.push(path.basename(site_dir));
             // Continue to remaining sites rather than abort the whole push
         }
     }
@@ -231,10 +248,12 @@ async function push_server(root_dir, options) {
             spinner.fail(`library: ${error instanceof Error ? error.message : error}`);
             if (is_auth_error(error))
                 saw_auth_error = true;
+            failed.push('library');
         }
     }
     if (saw_auth_error)
         print_auth_hint();
+    return failed;
 }
 async function push_single_site(site_dir, options, spinner) {
     let config = null;

package/dist/index.js

@@ -95,7 +95,7 @@ ${chalk.bold('See also')}
   primo deploy  Stand up a new hosted Primo server
   primo login   Authenticate with a hosted Primo server
 `)
-    .action((server, options) => push_site({ ...options, server: server || options.server }));
+    .action(async (server, options) => { await push_site({ ...options, server: server || options.server }); });
 program
     .command('pull [server] [dir]')
     .description('Pull entire server (all sites + library) to local files (defaults to ./<server-hostname>)')
@@ -169,4 +169,13 @@ program.on('command:*', (operands) => {
     console.error('');
     process.exit(1);
 });
-program.parse();
+// parseAsync so async action handlers are awaited inside commander's
+// lifecycle — with plain parse() a rejected handler becomes an unhandled
+// rejection (ugly stack, engine-dependent exit) instead of the clean
+// message + exit(1) below.
+program.parseAsync().catch((error) => {
+    console.error('');
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    console.error('');
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primo-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Local development CLI for Primo",
   "type": "module",
   "bin": {