primo-cli 0.1.21 → 0.1.23

package/dist/commands/add.d.ts

@@ -0,0 +1,6 @@
+interface AddOptions {
+    dir: string;
+    port: string;
+}
+export declare function add_site(target: string, options: AddOptions): Promise<void>;
+export {};

package/dist/commands/add.js

@@ -0,0 +1,345 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { randomInt } from 'crypto';
+import chalk from 'chalk';
+import ora from 'ora';
+import { spawn } from 'child_process';
+import { ensure_binary, ensure_data_dir } from '../utils/binary.js';
+import { read_site_config, write_site_config } from '../utils/site-config.js';
+import { SERVER_CONFIG_FILE, read_server_config, write_server_config } from '../utils/server-config.js';
+import { normalize_site } from './validate.js';
+import { import_site_files, site_exists, wait_for_ready, kill_process } from './dev.js';
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+function generate_id() {
+    let id = '';
+    for (let i = 0; i < 15; i++) {
+        id += ID_ALPHABET[randomInt(ID_ALPHABET.length)];
+    }
+    return id;
+}
+// Mirror of new.ts's display-name derivation so `primo add maison-verde`
+// and `primo new maison-verde` produce the same site name.
+function derive_display_name(folder_name) {
+    return folder_name.includes('.')
+        ? folder_name.split('.')[0].charAt(0).toUpperCase() + folder_name.split('.')[0].slice(1)
+        : folder_name.charAt(0).toUpperCase() + folder_name.slice(1).replace(/-/g, ' ');
+}
+// Register an existing sites/<name> folder with the workspace CMS: ensure
+// site.yaml has a site_id, then import the site's records into the workspace
+// database — via the running dev server when there is one, or a short-lived
+// headless CMS process otherwise. One-time action; exits when done.
+export async function add_site(target, options) {
+    const base_dir = path.resolve(options.dir);
+    try {
+        await fs.access(path.join(base_dir, SERVER_CONFIG_FILE));
+    }
+    catch {
+        console.log(chalk.red(`No ${SERVER_CONFIG_FILE} found in ${base_dir}.`));
+        console.log(chalk.dim('Run `primo add` from the workspace root, or pass --dir <workspace>.'));
+        process.exit(1);
+    }
+    const sites_root = path.join(base_dir, 'sites');
+    const site_dir = resolve_site_dir(base_dir, sites_root, target);
+    const folder_name = path.basename(site_dir);
+    let stat;
+    try {
+        stat = await fs.stat(site_dir);
+    }
+    catch {
+        console.log(chalk.red(`sites/${folder_name} not found.`));
+        console.log(chalk.dim('Create the folder first, or use `primo new` to scaffold a fresh site.'));
+        process.exit(1);
+    }
+    if (!stat.isDirectory()) {
+        console.log(chalk.red(`sites/${folder_name} is not a directory.`));
+        process.exit(1);
+    }
+    if (!await looks_like_site(site_dir)) {
+        console.log(chalk.red(`sites/${folder_name} doesn't look like a Primo site.`));
+        console.log(chalk.dim('Expected at least one of: site.yaml, pages/, blocks/, page-types/, site/'));
+        process.exit(1);
+    }
+    let server_config = await read_server_config(base_dir);
+    const { config, created, minted } = await ensure_site_config(site_dir, folder_name);
+    if (created) {
+        console.log(chalk.dim(`  created site.yaml (site_id ${config.site_id})`));
+    }
+    else if (minted) {
+        console.log(chalk.dim(`  stamped site_id ${config.site_id} into site.yaml`));
+    }
+    // `primo new` guarantees the default group exists in server.yaml; when we
+    // assign group: default ourselves, give it the same guarantee so the
+    // dashboard doesn't invent an ad-hoc group id for it.
+    if (config.group === 'default') {
+        const site_groups = server_config.site_groups ?? [];
+        if (!site_groups.some((group) => group.id === 'default')) {
+            server_config = {
+                ...server_config,
+                site_groups: [...site_groups, { id: 'default', name: 'Default', index: site_groups.length }]
+            };
+            await write_server_config(base_dir, server_config);
+        }
+    }
+    const port = server_config.port ?? parseInt(options.port, 10);
+    const api_url = `http://127.0.0.1:${port}`;
+    if (await is_server_running(port)) {
+        // A dev server is up — ask it to discover and import the site, exactly
+        // like `primo new` does, so its watchers attach too.
+        const reload = await request_dev_reload(port);
+        if (reload.status === 'unreachable') {
+            // Older dev server or hot reload disabled (port+1 in use). Import
+            // directly against the running CMS — records land, but the dev
+            // server won't watch this site until it's restarted.
+            let timings = null;
+            try {
+                timings = await register_site(site_dir, api_url, config, port, server_config, base_dir);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.log(chalk.red(`  ✗ ${config.name} could not be imported: ${message}`));
+                console.log(chalk.dim(`  Fix the problem, then re-run \`primo add ${target}\`.`));
+                process.exit(1);
+            }
+            report_import(config.name, timings);
+            console.log(chalk.yellow('  The running dev server couldn\'t be reloaded — restart `primo dev` to watch this site.'));
+            console.log('');
+            return;
+        }
+        // The health check only proves *a* Primo server is on this port — it
+        // could belong to a different workspace. The reload response's `known`
+        // list is the only reliable way to tell: PocketBase 404s record reads
+        // pre-setup even when the record exists, so we can't just probe the
+        // site_id. (Older dev servers don't send `known` — trust the reload.)
+        const known = reload.known?.find(site => site.site_id === config.site_id);
+        if (reload.known && !known) {
+            console.log(chalk.red(`  A Primo server is running on port ${port}, but it isn't serving this workspace.`));
+            console.log(chalk.dim('  Stop it (or start `primo dev` in this workspace) and re-run `primo add`.'));
+            process.exit(1);
+        }
+        if (known?.blocked || reload.quarantined.includes(config.name)) {
+            console.log(chalk.yellow(`  ${config.name} was found, but the dev server couldn't import it (e.g. duplicate IDs or a missing pages/index.yaml).`));
+            console.log(chalk.dim('  Check the `primo dev` logs, fix the problem, then re-run `primo add`.'));
+            process.exit(1);
+        }
+        console.log('');
+        if (reload.loaded === 0 && reload.known) {
+            console.log(`  ${chalk.cyan(config.name)} is already registered with the running dev server.`);
+        }
+        else {
+            console.log(chalk.green(`  ✓ ${config.name} registered`));
+        }
+        const host = local_dev_host(config.name, port);
+        console.log(`    ${chalk.dim('Edit:')}    http://${host}/admin/site`);
+        console.log(`    ${chalk.dim('Preview:')} http://${host}/`);
+        console.log('');
+        return;
+    }
+    // No dev server running: boot the CMS binary headlessly against the
+    // workspace database, import, and shut it back down.
+    const spinner = ora('Starting CMS for one-time import...').start();
+    const binary_path = await ensure_binary();
+    const data_dir = await ensure_data_dir(base_dir);
+    const cms_process = spawn(binary_path, ['serve', '--http', `127.0.0.1:${port}`, '--dir', data_dir], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, PRIMO_DEV_MODE: '1', PRIMO_AUTHOR_MODE: 'files' }
+    });
+    let stderr_output = '';
+    cms_process.stderr?.on('data', (data) => {
+        stderr_output += data.toString();
+    });
+    let timings = null;
+    let boot_failed = false;
+    let import_error = null;
+    try {
+        const ready = await wait_for_ready(api_url, 30000);
+        // A ready health check only proves *something* answered on the port.
+        // If our child lost the bind race to another CMS and exited, that
+        // other server is answering — importing would land this site's
+        // records in a different workspace's database. Require our own
+        // process to still be alive before trusting the port.
+        if (!ready || cms_process.exitCode !== null || cms_process.killed) {
+            boot_failed = true;
+        }
+        else {
+            spinner.text = `Importing ${config.name}...`;
+            try {
+                timings = await register_site(site_dir, api_url, config, port, server_config, base_dir);
+            }
+            catch (err) {
+                import_error = err instanceof Error ? err.message : String(err);
+            }
+        }
+    }
+    finally {
+        // Always tear the CMS down before exiting — process.exit skips
+        // finally blocks, so no exit() may appear inside this try.
+        await kill_process(cms_process);
+    }
+    if (boot_failed) {
+        spinner.fail('CMS failed to start');
+        if (stderr_output)
+            console.log(chalk.red(stderr_output));
+        process.exit(1);
+    }
+    if (import_error !== null) {
+        spinner.fail(`${config.name} could not be imported: ${import_error}`);
+        console.log(chalk.dim(`  Fix the problem, then re-run \`primo add ${target}\`.`));
+        process.exit(1);
+    }
+    if (timings === null || !timings.ok) {
+        // Duplicate _ids or a failed bootstrap+import — details already printed.
+        spinner.fail(`${config.name} could not be imported — see the errors above.`);
+        process.exit(1);
+    }
+    spinner.succeed(`${config.name} registered (${timings.mode})`);
+    report_warnings(timings);
+    console.log('');
+    console.log(chalk.dim('  Run `primo dev` to serve it.'));
+    console.log('');
+}
+async function register_site(site_dir, api_url, config, port, server_config, base_dir) {
+    await normalize_site(site_dir);
+    const use_bootstrap = !await site_exists(api_url, config.site_id);
+    return await import_site_files(site_dir, api_url, config, port, server_config, use_bootstrap, base_dir);
+}
+function report_import(site_name, timings) {
+    if (timings === null || !timings.ok) {
+        console.log(chalk.red(`  ✗ ${site_name} could not be imported — see the errors above.`));
+        process.exit(1);
+    }
+    console.log(chalk.green(`  ✓ ${site_name} registered (${timings.mode})`));
+    report_warnings(timings);
+}
+function report_warnings(timings) {
+    if (timings.warning_count > 0) {
+        console.log(chalk.yellow(`  ⚠ imported with ${timings.warning_count} warning${timings.warning_count === 1 ? '' : 's'} (details above)`));
+    }
+}
+function resolve_site_dir(base_dir, sites_root, target) {
+    // A bare name resolves under sites/; anything with a separator is taken
+    // as a path. Either way the result must be directly under sites/ — that's
+    // the only directory site discovery and the dashboard scan, so registering
+    // a folder anywhere else would import records no later `primo dev` run
+    // can match back to files.
+    const resolved = !target.includes('/') && !target.includes(path.sep)
+        ? path.resolve(sites_root, target)
+        : path.resolve(base_dir, target);
+    if (path.dirname(resolved) !== sites_root) {
+        console.log(chalk.red(`Sites must live directly under sites/ — got "${target}".`));
+        process.exit(1);
+    }
+    return resolved;
+}
+async function looks_like_site(site_dir) {
+    for (const marker of ['site.yaml', 'pages', 'blocks', 'page-types', 'site']) {
+        try {
+            await fs.stat(path.join(site_dir, marker));
+            return true;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return false;
+}
+// Make sure site.yaml exists with a name and a site_id, minting what's
+// missing. The site_id is the registration key: discovery, import, and the
+// dashboard all match records by it, so a folder without one can never come
+// online no matter how many times the dev server scans it.
+async function ensure_site_config(site_dir, folder_name) {
+    let existing = null;
+    try {
+        const parsed = await read_site_config(site_dir);
+        if (parsed && typeof parsed === 'object') {
+            existing = parsed;
+        }
+        else if (parsed !== null && parsed !== undefined) {
+            // site.yaml exists but isn't a mapping (e.g. a bare string).
+            // Overwriting it would silently discard whatever the user meant
+            // to keep — an empty file is the only non-mapping we fill in.
+            console.log(chalk.red(`sites/${folder_name}/site.yaml is malformed (expected key: value mappings).`));
+            console.log(chalk.dim('Fix or delete it, then re-run `primo add`.'));
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            // Unreadable or unparseable site.yaml — never overwrite it with a
+            // fresh config; that would mint a new site_id and drop the user's
+            // server/group for a site that may already be registered.
+            const message = error instanceof Error ? error.message : String(error);
+            console.log(chalk.red(`sites/${folder_name}/site.yaml could not be read: ${message}`));
+            console.log(chalk.dim('Fix or delete it, then re-run `primo add`.'));
+            process.exit(1);
+        }
+        // ENOENT — no site.yaml yet; create one below.
+    }
+    const created = existing === null;
+    const config = existing ?? { group: 'default' };
+    let changed = created;
+    if (!config.name) {
+        config.name = derive_display_name(folder_name);
+        changed = true;
+    }
+    const minted = !config.site_id;
+    if (minted) {
+        config.site_id = generate_id();
+        changed = true;
+    }
+    if (changed) {
+        await write_site_config(site_dir, config);
+    }
+    return { config, created, minted };
+}
+async function request_dev_reload(port) {
+    try {
+        // Bound the request: the reload handler runs discovery + import
+        // synchronously before responding.
+        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)
+            return { status: 'unreachable' };
+        const result = await res.json().catch(() => null);
+        if (!result)
+            return { status: 'unreachable' };
+        return {
+            status: 'ok',
+            loaded: result.loaded ?? 0,
+            quarantined: result.quarantined ?? [],
+            known: Array.isArray(result.known) ? result.known : undefined
+        };
+    }
+    catch {
+        return { status: 'unreachable' };
+    }
+}
+// Mirror of dev.ts's local_dev_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}`;
+}
+async function is_server_running(port) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1000);
+        const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: controller.signal
+        });
+        clearTimeout(timeout);
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/dev.d.ts

@@ -1,8 +1,32 @@
+import { type ChildProcess } from 'child_process';
+import { type SiteConfig } from '../utils/site-config.js';
+import { type ServerConfig } from '../utils/server-config.js';
 interface DevOptions {
     dir: string;
     port: string;
     force?: boolean;
     author?: string;
 }
+export type ImportTimings = {
+    zip_ms: number;
+    request_ms: number;
+    mode: 'bootstrap' | 'import' | 'bootstrap+import';
+    ok: boolean;
+    warning_count: number;
+    dropped_field_count: number;
+    warning_details: ImportWarning[];
+};
+export declare function kill_process(proc: ChildProcess): Promise<void>;
 export declare function dev_server(options: DevOptions): Promise<void>;
+export declare function wait_for_ready(url: string, timeout_ms: number): Promise<boolean>;
+export declare function site_exists(api_url: string, site_id: string): Promise<boolean>;
+export type ImportWarning = {
+    kind: string;
+    file: string;
+    path: string;
+    field: string;
+    block: string;
+    message: string;
+};
+export declare function import_site_files(site_dir: string, api_url: string, config: SiteConfig, port: number, server_config: ServerConfig, use_bootstrap?: boolean, workspace_dir?: string): Promise<ImportTimings | null>;
 export {};

package/dist/commands/dev.js

@@ -554,7 +554,7 @@ async function fetch_with_timeout(url, options = {}, timeout_ms = 10000) {
     }
 }
 // Kill process with escalation to SIGKILL
-async function kill_process(proc) {
+export async function kill_process(proc) {
     if (!proc || proc.killed)
         return;
     proc.kill('SIGTERM');
@@ -622,6 +622,13 @@ export async function dev_server(options) {
             // Single site mode
             try {
                 const config = await read_site_config(base_dir);
+                if (typeof config.site_id !== 'string' || !config.site_id.trim()) {
+                    // Without a site_id the import posts site_id=undefined and
+                    // fails cryptically — stop with the actual fix instead.
+                    spinner.fail(`${SITE_CONFIG_FILE} has no site_id — this site was never registered.`);
+                    console.log(chalk.dim(`  Run \`primo add ${path.basename(base_dir)}\` from the workspace root to register it.`));
+                    process.exit(1);
+                }
                 sites = [{ dir: base_dir, config }];
             }
             catch {
@@ -792,8 +799,8 @@ export async function dev_server(options) {
                     }
                     schedule_library_push();
                 };
-                const on_event = (full_path) => {
-                    if (should_skip_synced_delete(full_path))
+                const on_event = (event, full_path) => {
+                    if (should_skip_synced_delete(full_path, event))
                         return;
                     if (synced_files.has(full_path)) {
                         // We last wrote this file from a CMS pull. If the
@@ -876,11 +883,11 @@ export async function dev_server(options) {
                         }
                     }, LOCAL_PUSH_DEBOUNCE_MS);
                 };
-                watcher.on('add', on_event);
-                watcher.on('change', on_event);
-                watcher.on('unlink', on_event);
-                watcher.on('addDir', on_event);
-                watcher.on('unlinkDir', on_event);
+                watcher.on('add', p => on_event('add', p));
+                watcher.on('change', p => on_event('change', p));
+                watcher.on('unlink', p => on_event('unlink', p));
+                watcher.on('addDir', p => on_event('addDir', p));
+                watcher.on('unlinkDir', p => on_event('unlinkDir', p));
                 watchers.push(watcher);
             }
             catch {
@@ -1018,8 +1025,8 @@ export async function dev_server(options) {
                         mark_pending_local_change();
                         continue_event(full_path);
                     };
-                    const on_event = (full_path) => {
-                        if (should_skip_synced_delete(full_path))
+                    const on_event = (event, full_path) => {
+                        if (should_skip_synced_delete(full_path, event))
                             return;
                         if (synced_files.has(full_path)) {
                             // We last wrote this file from a CMS pull. Compare
@@ -1045,11 +1052,11 @@ export async function dev_server(options) {
                         }
                         push_or_ignore_file_change(full_path);
                     };
-                    watcher.on('add', on_event);
-                    watcher.on('change', on_event);
-                    watcher.on('unlink', on_event);
-                    watcher.on('addDir', on_event);
-                    watcher.on('unlinkDir', on_event);
+                    watcher.on('add', p => on_event('add', p));
+                    watcher.on('change', p => on_event('change', p));
+                    watcher.on('unlink', p => on_event('unlink', p));
+                    watcher.on('addDir', p => on_event('addDir', p));
+                    watcher.on('unlinkDir', p => on_event('unlinkDir', p));
                     watchers.push(watcher);
                 }
                 catch {
@@ -1078,37 +1085,52 @@ export async function dev_server(options) {
                         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);
-                    }
-                    else {
-                        await normalize_site(site.dir);
-                        const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, use_bootstrap, base_dir));
-                        if (import_timings === null) {
-                            // 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;
+                    try {
+                        const use_bootstrap = !await site_exists(api_url, site.config.site_id);
+                        if (sync_policy.mode === 'cms' && !use_bootstrap) {
+                            await sync_from_cms(site.dir, api_url, site.config, server_config, base_dir, sync_policy);
                         }
                         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.
+                            await normalize_site(site.dir);
+                            const import_timings = await with_site_import_lock(site.dir, site.config, () => import_site_files(site.dir, api_url, site.config, port, server_config, use_bootstrap, base_dir));
+                            if (import_timings === null) {
+                                // 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);
+                                }
                             }
                         }
                     }
+                    catch (err) {
+                        // A malformed site (e.g. missing pages/index.yaml, which makes
+                        // normalize_site throw) must not take the whole dev server down:
+                        // before this guard, the throw escaped the handler as an
+                        // unhandledRejection and tripped process-level cleanup().
+                        // Quarantine the site and keep serving; the watcher retries it
+                        // on the next file change.
+                        blocked_site_keys.add(get_site_sync_key(site.dir, site.config));
+                        quarantined.push(site.config.name);
+                        import_ok = false;
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.log(chalk.red(`  ✗ ${site.config.name}: ${message}`));
+                    }
                     setup_site_watchers(site);
                     loaded_count++;
                     if (!import_ok) {
@@ -1124,9 +1146,18 @@ export async function dev_server(options) {
                 // 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.
+                // `known` lists every site this server tracks so `primo add` can
+                // tell "already registered here" from "this server is serving a
+                // different workspace" — record-level reads can't make that call
+                // (PocketBase 404s them pre-setup even when the record exists).
                 const body = JSON.stringify({
                     loaded: loaded_count,
-                    quarantined
+                    quarantined,
+                    known: sites.map(site => ({
+                        name: site.config.name,
+                        site_id: site.config.site_id,
+                        blocked: blocked_site_keys.has(get_site_sync_key(site.dir, site.config))
+                    }))
                 });
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(body);
@@ -1279,6 +1310,33 @@ async function register_primo_mcp_server(base_dir) {
 function is_plain_record(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
+// Folders that already got their unregistered/unreadable warning, so
+// rediscovery (which runs on every /reload) doesn't repeat it.
+const warned_unregistered_dirs = new Set();
+// Site-shaped = has any of the content dirs a real site carries. Used to
+// tell an authored-but-unregistered site (warn) from a random folder that
+// happens to live under sites/ (ignore silently, as before).
+async function is_site_shaped(site_dir) {
+    for (const marker of ['pages', 'blocks', 'page-types', 'site']) {
+        try {
+            // Must be a directory — a plain file named e.g. `pages` in a
+            // non-site folder shouldn't earn the unregistered warning.
+            const stat = await fs.stat(path.join(site_dir, marker));
+            if (stat.isDirectory())
+                return true;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return false;
+}
+function warn_once(site_dir, message) {
+    if (warned_unregistered_dirs.has(site_dir))
+        return;
+    warned_unregistered_dirs.add(site_dir);
+    console.log(chalk.yellow(message));
+}
 async function discover_sites(base_dir) {
     const sites = [];
     const sites_root = await get_sites_root(base_dir);
@@ -1288,10 +1346,26 @@ async function discover_sites(base_dir) {
             const site_dir = path.join(sites_root, entry.name);
             try {
                 const config = await read_site_config(site_dir);
+                if (typeof config.site_id !== 'string' || !config.site_id.trim()) {
+                    // An authored site with no registration key. Importing it
+                    // would post site_id=undefined and die with a buried
+                    // error, so skip it and say what to run instead.
+                    warn_once(site_dir, `  ⚠ sites/${entry.name} isn't registered — run \`primo add ${entry.name}\` to import it.`);
+                    continue;
+                }
                 sites.push({ dir: site_dir, config });
             }
-            catch {
-                // Not a site directory
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // No site.yaml. Only warn when the folder actually looks
+                    // like a site — anything else is not our business.
+                    if (await is_site_shaped(site_dir)) {
+                        warn_once(site_dir, `  ⚠ sites/${entry.name} isn't registered — run \`primo add ${entry.name}\` to import it.`);
+                    }
+                }
+                else {
+                    warn_once(site_dir, `  ⚠ sites/${entry.name}/site.yaml could not be read — fix it, then run \`primo add ${entry.name}\`.`);
+                }
             }
         }
     }
@@ -1337,7 +1411,7 @@ function resolve_site_group(config, server_config) {
         index: 0
     });
 }
-async function wait_for_ready(url, timeout_ms) {
+export async function wait_for_ready(url, timeout_ms) {
     const start = Date.now();
     const health_url = `${url}/api/health`;
     while (Date.now() - start < timeout_ms) {
@@ -1374,7 +1448,7 @@ async function verify_site_ready(api_url, site_id) {
     }
     return false;
 }
-async function site_exists(api_url, site_id) {
+export async function site_exists(api_url, site_id) {
     // Only 404 means the site genuinely doesn't exist. Any other non-ok status
     // (401/403 from auth, 5xx, rate limits) leaves us uncertain — default to
     // "exists" so we take the additive `import` path instead of the destructive
@@ -1462,11 +1536,21 @@ function mark_written_file(file_path, content) {
 function mark_deleted_path(file_path) {
     synced_deleted_paths.set(file_path, Date.now());
 }
-function should_skip_synced_delete(file_path) {
+function is_delete_event(event) {
+    return event === 'unlink' || event === 'unlinkDir';
+}
+function should_skip_synced_delete(file_path, event) {
     const deleted_at = synced_deleted_paths.get(file_path);
     if (!deleted_at) {
         return false;
     }
+    // A re-creation cancels the pending delete-echo suppression and must be
+    // allowed through to import. Clear the marker so a later real delete of the
+    // same path isn't mistaken for our echo.
+    if (!is_delete_event(event)) {
+        synced_deleted_paths.delete(file_path);
+        return false;
+    }
     if (Date.now() - deleted_at < 10_000) {
         synced_deleted_paths.delete(file_path);
         return true;
@@ -2026,7 +2110,7 @@ function print_import_warnings(site_name, warnings) {
     console.log('');
     return list.length;
 }
-async function import_site_files(site_dir, api_url, config, port, server_config, use_bootstrap = true, workspace_dir = path.dirname(path.dirname(site_dir))) {
+export async function import_site_files(site_dir, api_url, config, port, server_config, use_bootstrap = true, workspace_dir = path.dirname(path.dirname(site_dir))) {
     const site_name = config.name || 'My Site';
     const site_id = config.site_id;
     const site_group = resolve_site_group(config, server_config);

package/dist/commands/new.d.ts

@@ -4,4 +4,5 @@ interface NewOptions {
     skipDev?: boolean;
 }
 export declare function new_site(options: NewOptions): Promise<void>;
+export declare function generate_agent_md(): string;
 export {};

package/dist/commands/new.js

@@ -375,7 +375,7 @@ async function is_server_running(port) {
         return false;
     }
 }
-function generate_agent_md() {
+export function generate_agent_md() {
     return `# Primo workspace
 
 Primo workspace for local development. Each subdirectory under \`sites/\` is an independent Primo site.
@@ -394,6 +394,7 @@ Without the MCP server, read \`sites/*/blocks/*/fields.yaml\` and \`sites/*/page
 
 - \`primo dev\` — start the local CMS and dev server. Run from the workspace root.
 - \`primo new [name]\` — scaffold a new site under \`sites/\`.
+- \`primo add <name>\` — register an existing \`sites/<name>\` folder with the CMS (mints its site_id and imports its records). Creating the folder alone doesn't register it.
 - File edits sync automatically while \`primo dev\` is running. Structural changes (block schema, component) may trigger a browser reload.
 
 ## Source of truth

package/dist/commands/pull.js

@@ -8,6 +8,7 @@ import { get_auth_token } from '../utils/auth.js';
 import { authenticate_interactively } from './login.js';
 import { write_site_config } from '../utils/site-config.js';
 import { read_server_config, write_server_config, normalize_server_url } from '../utils/server-config.js';
+import { generate_agent_md } from './new.js';
 // Directories owned by the server export. Local files under these that no
 // longer exist in the export are stale (e.g. a page that gained children
 // moved from pages/foo.yaml to pages/foo/index.yaml) and get trashed.
@@ -182,6 +183,18 @@ export async function pull_site(options) {
             site_groups: site_groups.length > 0 ? site_groups : existing?.site_groups,
             server: existing?.server ?? (is_remote_server(server) ? server : undefined)
         });
+        // Give pulled workspaces the same root AGENTS.md that `primo new`
+        // writes — a pulled export is exactly where agents author new site
+        // folders and need to know registration is `primo add`, not a side
+        // effect of `primo dev`. Never clobber an existing (possibly edited)
+        // one.
+        const agents_path = path.join(root_dir, 'AGENTS.md');
+        try {
+            await fs.access(agents_path);
+        }
+        catch {
+            await fs.writeFile(agents_path, generate_agent_md());
+        }
         spinner.succeed(`Server pulled to ${chalk.cyan(root_dir)}`);
         console.log('');
         console.log(chalk.dim('  Sites:'));

package/dist/index.js

@@ -6,6 +6,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { init_workspace } from './commands/init.js';
 import { new_site } from './commands/new.js';
+import { add_site } from './commands/add.js';
 import { pull_site } from './commands/pull.js';
 import { push_site } from './commands/push.js';
 import { pull_library } from './commands/pull-library.js';
@@ -28,6 +29,7 @@ program
 program.addHelpText('before', `
 ${chalk.bold('Local development')}
   ${chalk.cyan('primo dev')}      Run the local CMS on this workspace
+  ${chalk.cyan('primo add')}      Register a hand-authored sites/ folder with the CMS
 
 ${chalk.bold('Going live — pick one')}
   Want others to edit content? .................. ${chalk.cyan('primo deploy')}
@@ -44,6 +46,22 @@ program
     .option('-t, --template <template>', 'Starter template')
     .option('--skip-dev', 'Create files only, don\'t start CMS')
     .action((name, options) => new_site({ name, ...options }));
+program
+    .command('add <site>')
+    .description('Register an existing sites/ folder with the workspace CMS, then exit')
+    .option('-d, --dir <dir>', 'Workspace directory', '.')
+    .option('-p, --port <port>', 'Port', '3000')
+    .addHelpText('after', `
+Creating a folder under ${chalk.cyan('sites/')} isn't enough to make it appear in the
+dashboard — its records must be imported into the workspace database. This
+command does that one-time import (minting a site_id into site.yaml if needed)
+and exits. If ${chalk.cyan('primo dev')} is already running, it picks the site up live.
+
+${chalk.bold('Examples')}
+  primo add maison-verde
+  primo add sites/maison-verde
+`)
+    .action((site, options) => add_site(site, options));
 program
     .command('dev')
     .description('Start local CMS')
@@ -163,6 +181,14 @@ program.on('command:*', (operands) => {
         console.error('');
         console.error(`  Run: ${chalk.cyan('primo deploy --help')}`);
     }
+    else if (cmd === 'register' || cmd === 'import') {
+        // Likely guesses for site registration. Deliberately not aliases:
+        // one canonical name keeps docs/transcripts consistent, and leaves
+        // `register` free for a future account/signup meaning.
+        console.error(`  To register an existing sites/ folder with the CMS, run ${chalk.cyan('primo add <site>')}.`);
+        console.error('');
+        console.error(`  Run: ${chalk.cyan('primo add --help')}`);
+    }
     else {
         console.error(`  Run ${chalk.cyan('primo --help')} to see available commands.`);
     }

package/package.json

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