smoodly 0.0.30 → 0.0.32

package/README.md

@@ -587,6 +587,20 @@ Implemented:
   but `smoodly/admin/next` reaches no client module except those two),
   `examples/site/e2e/site-bundle.spec.ts` (CI only: production chunks).
 
+- Export and import (spec 2026-09-28 export/import): `npx smoodly export
+  [--out <dir>]` writes the key's space — the nine content tables with
+  history, the member list, the ready assets' files — into a folder
+  (`manifest.json`, `rows/<table>.json` without `space_id`, `media/`
+  without the space prefix), written as `.partial` and renamed last; it
+  refuses a publishable key (the `smoodly_meta` read), a database behind
+  the package, and a snapshot whose foreign keys do not close ("content
+  changed during export"). `npx smoodly import <dir>` writes it into a
+  space that is empty or holds only this export's rows, schema versions
+  equal: media first, rows in reference order with on-conflict-do-nothing,
+  so a stopped run finishes by running it again. Tests: `space-transfer`,
+  `cli-transfer`, `space-transfer.supabase`,
+  `examples/site/e2e/transfer.spec.ts`.
+
 Not yet: canvas drag-and-drop (list fields, the outline, manual
 collections and the pages tree drag since 2026-09-09 — spec
 `docs/superpowers/specs/2026-09-09-drag-and-drop-design.md`), undo/redo, sample/placeholder content
@@ -613,6 +627,30 @@ after both are on the registry. From the repo root:
 `prepublishOnly` rebuilds each package. The Claude Code skill
 `.claude/skills/releasing-smoodly` carries the same order with its checks.
 
+## Follow-ups (logged 2026-09-28, export/import spec)
+
+- `import --replace`: delete the space's content and media first, after
+  typing the space to confirm — a backup restored over a live project.
+  Mention it in the not-empty refusal when it lands.
+- A copy inside one database with fresh IDs — the cloud's "duplicate
+  environment", staging → production; needs the reference walk (parent
+  links, version pointers, refs, paths, asset ids in trees, fields and
+  richtext) the eject avoids by keeping IDs.
+- A readable export for leaving Smoodly: one document per page or entry,
+  fields resolved, no internal IDs.
+- A "Download backup" button in the admin: the same export behind an op,
+  zipped for an editor.
+- A ready asset whose `poster_id` names a pending asset would fail the
+  export's consistency check on every run (pending assets are not
+  exported). Unverified whether the upload flow can leave that state;
+  if it can, export the poster or null the pointer with a warning.
+- Import cannot expire the app's cache tags; it prints a restart note. A
+  revalidate call through the app (an op the CLI could reach) would make
+  the note unnecessary.
+- A resumed import that lands nothing still prints the full "Imported …"
+  summary and the member list — accurate (the space holds all of it) but
+  noisy; count what actually landed and say "nothing new" when it is zero.
+
 ## Follow-ups (logged 2026-09-27, shadowed-page detector spec)
 
 - A section's crash on a live page after data changed outside the page

package/dist/cli/export.d.ts

@@ -0,0 +1,14 @@
+import { type SpaceConnection } from "./space-io.ts";
+export type ExportArgs = {
+    out: string | null;
+};
+export type ExportDeps = {
+    cwd?: string;
+    connection?: SpaceConnection;
+    now?: () => Date;
+};
+export declare const defaultExportDir: (now: Date) => string;
+export declare const folderExists: (dir: string) => string;
+export declare const CHANGED_DURING_EXPORT = "Content changed during export \u2014 run it again.";
+export declare const missingFile: (path: string) => string;
+export declare function runExport(args: ExportArgs, out: (line: string) => void, deps?: ExportDeps): Promise<number>;

package/dist/cli/export.js

@@ -0,0 +1,96 @@
+// packages/smoodly/src/cli/export.ts
+// `smoodly export` (spec 2026-09-28 export/import §8): the key's space —
+// every content row, history included, and the media files — into a
+// folder. Reads only; the folder appears whole or not at all (written as
+// <dir>.partial, renamed last). The message strings are what the guide
+// quotes.
+import { existsSync } from "node:fs";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { schemaBehind, schemaBehindMessage } from "../schema-version.js";
+import { CONTENT_TABLES } from "../sql-space.js";
+import { FORMAT, brokenReferences, countRows, describeExport, emptyTables, fromSpace, sortRows, } from "../space-transfer.js";
+import { MEDIA_BUCKET, connectFromEnv, isNotFound, packageVersion, readSchemaVersion, readSpaceRows, schemaRefusal, } from "./space-io.js";
+export const defaultExportDir = (now) => `smoodly-export-${now.toISOString().slice(0, 10)}`;
+export const folderExists = (dir) => `Refusing: ${dir} already exists. Remove it, or pass --out <dir>.`;
+export const CHANGED_DURING_EXPORT = "Content changed during export — run it again.";
+export const missingFile = (path) => `Warning: ${path} is missing from the media bucket (already broken on the site); its asset row is exported without a file.`;
+export async function runExport(args, out, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const now = (deps.now ?? (() => new Date()))();
+    const dir = resolve(cwd, args.out ?? defaultExportDir(now));
+    // Relative when inside the app's folder, absolute when --out points elsewhere.
+    const rel = relative(cwd, dir);
+    const shown = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : dir;
+    if (existsSync(dir)) {
+        out(folderExists(shown));
+        return 1;
+    }
+    const { db, space } = deps.connection ?? connectFromEnv(cwd);
+    const schema = await readSchemaVersion(db);
+    if ("missing" in schema) {
+        out(schemaRefusal(schema.missing, "Export"));
+        return 1;
+    }
+    if (schemaBehind(schema.version)) {
+        out(schemaBehindMessage(schema.version));
+        return 1;
+    }
+    const rows = emptyTables();
+    for (const table of CONTENT_TABLES) {
+        const read = await readSpaceRows(db, table, space, table === "assets" ? { status: "ready" } : {});
+        rows[table] = sortRows(table, read.map((row) => fromSpace(table, row, space)));
+    }
+    const broken = brokenReferences(rows);
+    if (broken.length > 0) {
+        out(CHANGED_DURING_EXPORT);
+        for (const line of broken.slice(0, 10))
+            out(`  ${line}`);
+        return 1;
+    }
+    const members = await db.from("members").select("email, role").eq("space_id", space).order("email");
+    if (members.error)
+        throw new Error(`smoodly: reading members: ${members.error.message}`);
+    const partial = `${dir}.partial`;
+    await rm(partial, { recursive: true, force: true });
+    await mkdir(join(partial, "rows"), { recursive: true });
+    await mkdir(join(partial, "media"), { recursive: true });
+    const missing = [];
+    let files = 0;
+    let bytes = 0;
+    for (const asset of rows.assets) {
+        const path = String(asset.path);
+        const got = await db.storage.from(MEDIA_BUCKET).download(`${space}/${path}`);
+        if (got.error) {
+            if (!isNotFound(got.error))
+                throw new Error(`smoodly: downloading ${path}: ${got.error.message}`);
+            missing.push(path);
+            out(missingFile(path));
+            continue;
+        }
+        const data = new Uint8Array(await got.data.arrayBuffer());
+        const file = join(partial, "media", path);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, data);
+        files++;
+        bytes += data.byteLength;
+    }
+    for (const table of CONTENT_TABLES) {
+        await writeFile(join(partial, "rows", `${table}.json`), `${JSON.stringify(rows[table], null, 2)}\n`);
+    }
+    const manifest = {
+        format: FORMAT,
+        schemaVersion: schema.version,
+        smoodlyVersion: packageVersion(),
+        exportedAt: now.toISOString(),
+        sourceSpace: space,
+        counts: countRows(rows),
+        media: { files, bytes, missing },
+        members: (members.data ?? []),
+    };
+    await writeFile(join(partial, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    await rename(partial, dir);
+    out(`Exported space ${space}: ${describeExport(rows, bytes)}`);
+    out(`→ ${shown}/`);
+    return 0;
+}

package/dist/cli/import.d.ts

@@ -0,0 +1,19 @@
+import { type ContentTable } from "../sql-space.ts";
+import { type SpaceConnection } from "./space-io.ts";
+export type ImportArgs = {
+    dir: string;
+};
+export type ImportDeps = {
+    cwd?: string;
+    connection?: SpaceConnection;
+    batchSize?: number;
+    /** Test seam: runs before each batch; a throw stops the import there. */
+    beforeBatch?: (table: ContentTable, index: number) => void;
+};
+export declare const BATCH_ROWS = 500;
+export declare const notAnExport: (dir: string) => string;
+export declare const formatMismatch: (format: unknown) => string;
+export declare const RUN_AGAIN = "Run the same command again to continue: rows and files that landed are skipped.";
+export declare const MEMBERS_HEADING = "Members in the source \u2014 invite them in Settings \u203A Members:";
+export declare const CACHE_NOTE = "Restart or redeploy the app: it may have cached pages from while the space was empty.";
+export declare function runImport(args: ImportArgs, out: (line: string) => void, deps?: ImportDeps): Promise<number>;

package/dist/cli/import.js

@@ -0,0 +1,93 @@
+// packages/smoodly/src/cli/import.ts
+// `smoodly import <dir>` (spec 2026-09-28 export/import §9–§10): an
+// export folder into the key's space. Every check runs before the first
+// write; nothing is overwritten or deleted; a run that stops midway is
+// finished by running it again, since the target may hold only this
+// export's rows and both writes skip what already landed.
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { MEDIA_CACHE_SECONDS } from "../media.js";
+import { CONTENT_TABLES } from "../sql-space.js";
+import { CONFLICT_COLUMNS, FORMAT, ROW_KEY, describeImport, emptyTables, foreignRows, insertPlan, intoSpace, notEmptyMessage, rowKey, versionMismatchMessage, } from "../space-transfer.js";
+import { MEDIA_BUCKET, connectFromEnv, isAlreadyExists, readSchemaVersion, readSpaceRows, schemaRefusal, } from "./space-io.js";
+export const BATCH_ROWS = 500;
+export const notAnExport = (dir) => `Refusing: ${dir} is not a Smoodly export (no manifest.json).`;
+export const formatMismatch = (format) => `Refusing: this export's format is ${String(format)}; this smoodly reads format ${FORMAT}. Update smoodly.`;
+export const RUN_AGAIN = "Run the same command again to continue: rows and files that landed are skipped.";
+export const MEMBERS_HEADING = "Members in the source — invite them in Settings › Members:";
+export const CACHE_NOTE = "Restart or redeploy the app: it may have cached pages from while the space was empty.";
+export async function runImport(args, out, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const dir = resolve(cwd, args.dir);
+    const manifestFile = join(dir, "manifest.json");
+    if (!existsSync(manifestFile)) {
+        out(notAnExport(args.dir));
+        return 1;
+    }
+    const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+    if (manifest.format !== FORMAT) {
+        out(formatMismatch(manifest.format));
+        return 1;
+    }
+    const { db, space } = deps.connection ?? connectFromEnv(cwd);
+    const schema = await readSchemaVersion(db);
+    if ("missing" in schema) {
+        out(schemaRefusal(schema.missing, "Import"));
+        return 1;
+    }
+    if (schema.version !== manifest.schemaVersion) {
+        out(versionMismatchMessage(schema.version, manifest.schemaVersion));
+        return 1;
+    }
+    const rows = emptyTables();
+    for (const table of CONTENT_TABLES)
+        rows[table] = JSON.parse(await readFile(join(dir, "rows", `${table}.json`), "utf8"));
+    const target = {};
+    for (const table of CONTENT_TABLES) {
+        target[table] = (await readSpaceRows(db, table, space, {}, ROW_KEY[table].join(","))).map((row) => rowKey(table, row));
+    }
+    const foreign = foreignRows(target, rows);
+    if (CONTENT_TABLES.some((t) => foreign[t] > 0)) {
+        out(notEmptyMessage(foreign));
+        return 1;
+    }
+    try {
+        // Media first, so no ready asset row ever points at a missing file.
+        for (const asset of rows.assets) {
+            const path = String(asset.path);
+            const file = join(dir, "media", path);
+            if (!existsSync(file))
+                continue; // missing in the source as well (manifest.media.missing)
+            const up = await db.storage.from(MEDIA_BUCKET).upload(`${space}/${path}`, await readFile(file), {
+                contentType: String(asset.mime),
+                upsert: false,
+                cacheControl: String(MEDIA_CACHE_SECONDS),
+            });
+            if (up.error && !isAlreadyExists(up.error))
+                throw new Error(`uploading ${path}: ${up.error.message}`);
+        }
+        const size = deps.batchSize ?? BATCH_ROWS;
+        for (const { table, rows: list } of insertPlan(rows)) {
+            for (let i = 0; i * size < list.length; i++) {
+                deps.beforeBatch?.(table, i);
+                const batch = list.slice(i * size, (i + 1) * size).map((row) => intoSpace(table, row, space));
+                const res = await db.from(table).upsert(batch, { onConflict: CONFLICT_COLUMNS[table], ignoreDuplicates: true });
+                if (res.error)
+                    throw new Error(`inserting ${table}: ${res.error.message}`);
+            }
+        }
+    }
+    catch (e) {
+        out(`Import stopped: ${e instanceof Error ? e.message : String(e)}`);
+        out(RUN_AGAIN);
+        return 1;
+    }
+    out(`Imported ${describeImport(rows)} into space ${space}.`);
+    if (manifest.members.length > 0) {
+        out(MEMBERS_HEADING);
+        out(`  ${manifest.members.map((m) => `${m.email ?? "(no email)"} (${m.role})`).join(", ")}`);
+    }
+    out(CACHE_NOTE);
+    return 0;
+}

package/dist/cli/main.d.ts

@@ -1,8 +1,16 @@
 import { type MigrateArgs } from "./migrate.ts";
-export declare const USAGE = "usage: smoodly migrate [--check] [--collections <file>] [--migrations <dir>]\n\n  Copies the core schema files this package ships that supabase/migrations/\n  lacks, and writes one views file for the collections whose view is new or\n  changed. Prints the push or reset command; never runs it.\n\n  --check              write nothing; exit 1 when anything is pending\n  --collections <file> the module exporting `collections` (default smoodly/collections.ts)\n  --migrations <dir>   the app's migration folder (default supabase/migrations)";
+import { type ExportArgs } from "./export.ts";
+import { type ImportArgs } from "./import.ts";
+export declare const USAGE = "usage: smoodly <command>\n\n  migrate [--check] [--collections <file>] [--migrations <dir>]\n    Copies the core schema files this package ships that supabase/migrations/\n    lacks, and writes one views file for the collections whose view is new or\n    changed. Prints the push or reset command; never runs it.\n\n    --check              write nothing; exit 1 when anything is pending\n    --collections <file> the module exporting `collections` (default smoodly/collections.ts)\n    --migrations <dir>   the app's migration folder (default supabase/migrations)\n\n  export [--out <dir>]\n    Writes the space SMOODLY_SECRET_KEY names \u2014 every content row, history\n    included, and the media files \u2014 into a folder (default\n    smoodly-export-<date>). Reads only.\n\n  import <dir>\n    Writes an export folder into the key's space, which must be empty or hold\n    only this export's rows (an earlier run to continue). Never deletes.";
 export type Parsed = {
     command: "migrate";
     args: MigrateArgs;
+} | {
+    command: "export";
+    args: ExportArgs;
+} | {
+    command: "import";
+    args: ImportArgs;
 } | {
     command: "help";
 } | {

package/dist/cli/main.js

@@ -1,24 +1,51 @@
 // packages/smoodly/src/cli/main.ts
-// `smoodly` — the package's command line (spec 2026-09-26 §2). One
-// subcommand for now; `check`, `export` and the drift report land here
-// later. Exit codes: 0 done or nothing to do, 1 pending (--check) or a
-// refused file, 2 usage.
+// `smoodly` — the package's command line. Three subcommands: migrate
+// (spec 2026-09-26 §2), export and import (spec 2026-09-28). Exit codes:
+// 0 done or nothing to do, 1 pending (--check), refused or failed, 2 usage.
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runMigrate } from "./migrate.js";
-export const USAGE = `usage: smoodly migrate [--check] [--collections <file>] [--migrations <dir>]
+import { runExport } from "./export.js";
+import { runImport } from "./import.js";
+export const USAGE = `usage: smoodly <command>
 
-  Copies the core schema files this package ships that supabase/migrations/
-  lacks, and writes one views file for the collections whose view is new or
-  changed. Prints the push or reset command; never runs it.
+  migrate [--check] [--collections <file>] [--migrations <dir>]
+    Copies the core schema files this package ships that supabase/migrations/
+    lacks, and writes one views file for the collections whose view is new or
+    changed. Prints the push or reset command; never runs it.
 
-  --check              write nothing; exit 1 when anything is pending
-  --collections <file> the module exporting \`collections\` (default smoodly/collections.ts)
-  --migrations <dir>   the app's migration folder (default supabase/migrations)`;
+    --check              write nothing; exit 1 when anything is pending
+    --collections <file> the module exporting \`collections\` (default smoodly/collections.ts)
+    --migrations <dir>   the app's migration folder (default supabase/migrations)
+
+  export [--out <dir>]
+    Writes the space SMOODLY_SECRET_KEY names — every content row, history
+    included, and the media files — into a folder (default
+    smoodly-export-<date>). Reads only.
+
+  import <dir>
+    Writes an export folder into the key's space, which must be empty or hold
+    only this export's rows (an earlier run to continue). Never deletes.`;
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
     if (!command || command === "--help" || command === "-h" || command === "help")
         return { command: "help" };
+    if (command === "export") {
+        const args = { out: null };
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === "--out" && rest[i + 1] !== undefined)
+                args.out = rest[++i];
+            else
+                return { command: "error", message: `unexpected argument "${a}"` };
+        }
+        return { command: "export", args };
+    }
+    if (command === "import") {
+        if (rest.length !== 1 || rest[0].startsWith("-"))
+            return { command: "error", message: "import needs one export folder: smoodly import <dir>" };
+        return { command: "import", args: { dir: rest[0] } };
+    }
     if (command !== "migrate")
         return { command: "error", message: `unknown command "${command}"` };
     const args = { check: false, collections: "smoodly/collections.ts", migrations: "supabase/migrations" };
@@ -46,6 +73,10 @@ export async function main(argv, out = console.log) {
         return 2;
     }
     try {
+        if (parsed.command === "import")
+            return await runImport(parsed.args, out);
+        if (parsed.command === "export")
+            return await runExport(parsed.args, out);
         return await runMigrate(parsed.args, out);
     }
     catch (e) {

package/dist/cli/space-io.d.ts

@@ -0,0 +1,33 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { ContentTable } from "../sql-space.ts";
+import { type Row } from "../space-transfer.ts";
+export type SpaceConnection = {
+    db: SupabaseClient;
+    space: string;
+};
+export declare const MEDIA_BUCKET = "media";
+/** Rows per request. A host may cap below it, so a read stops at the first empty page, not the first short one. */
+export declare const PAGE_ROWS = 1000;
+/** `.env.local`, then `.env`, as Next reads them; a variable already set wins (spec §5). */
+export declare function loadAppEnv(cwd: string, env?: Record<string, string | undefined>): void;
+/** The app's content client and the space its secret key names: a cloud key's claim, or the default space. */
+export declare function connectFromEnv(cwd: string): SpaceConnection;
+/** The policies show `smoodly_meta` to a write key only, so no visible row means the key is not a secret key (spec §5). */
+export declare function readSchemaVersion(db: SupabaseClient): Promise<{
+    version: number;
+} | {
+    missing: "key" | "schema";
+}>;
+export declare function schemaRefusal(missing: "key" | "schema", command: "Export" | "Import"): string;
+/** Every row of one table in one space, paged in primary-key order. The space filter is explicit: a service-role key sees every space. */
+export declare function readSpaceRows(db: SupabaseClient, table: ContentTable, space: string, where?: Record<string, string>, columns?: string): Promise<Row[]>;
+type StorageErrorLike = {
+    message: string;
+    statusCode?: string | number;
+    status?: number;
+};
+export declare const isNotFound: (e: StorageErrorLike) => boolean;
+export declare const isAlreadyExists: (e: StorageErrorLike) => boolean;
+/** The installed package's version for the manifest: `../../package.json` from src/cli/ and dist/cli/ alike. */
+export declare function packageVersion(): string;
+export {};

package/dist/cli/space-io.js

@@ -0,0 +1,77 @@
+// packages/smoodly/src/cli/space-io.ts
+// What export and import share (spec 2026-09-28 export/import §5, §8):
+// the app's env, the client and the space its key names, the schema-
+// version read that doubles as the secret-key check, paged reads of one
+// space's rows, and the two storage error tests.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { createSmoodlyClient } from "../client.js";
+import { resolveSmoodlyEnv, spaceIdOfKey } from "../env.js";
+import { SCHEMA_VERSION_KEY } from "../schema-version.js";
+import { ROW_KEY } from "../space-transfer.js";
+export const MEDIA_BUCKET = "media";
+/** Rows per request. A host may cap below it, so a read stops at the first empty page, not the first short one. */
+export const PAGE_ROWS = 1000;
+/** `.env.local`, then `.env`, as Next reads them; a variable already set wins (spec §5). */
+export function loadAppEnv(cwd, env = process.env) {
+    for (const name of [".env.local", ".env"]) {
+        const file = join(cwd, name);
+        if (!existsSync(file))
+            continue;
+        for (const [key, value] of Object.entries(parseEnv(readFileSync(file, "utf8")))) {
+            if (env[key] === undefined)
+                env[key] = value;
+        }
+    }
+}
+/** The app's content client and the space its secret key names: a cloud key's claim, or the default space. */
+export function connectFromEnv(cwd) {
+    loadAppEnv(cwd);
+    const env = resolveSmoodlyEnv(process.env);
+    return { db: createSmoodlyClient(env), space: spaceIdOfKey(env.secretKey) };
+}
+/** The policies show `smoodly_meta` to a write key only, so no visible row means the key is not a secret key (spec §5). */
+export async function readSchemaVersion(db) {
+    const res = await db.from("smoodly_meta").select("value").eq("key", SCHEMA_VERSION_KEY).maybeSingle();
+    if (res.error) {
+        // PGRST205: not in PostgREST's schema cache; 42P01: undefined table; 42501: no grant.
+        if (res.error.code === "PGRST205" || res.error.code === "42P01")
+            return { missing: "schema" };
+        if (res.error.code === "42501")
+            return { missing: "key" };
+        throw new Error(`smoodly: reading the schema version: ${res.error.message}`);
+    }
+    const n = Number(res.data?.value);
+    return res.data && Number.isInteger(n) ? { version: n } : { missing: "key" };
+}
+export function schemaRefusal(missing, command) {
+    return missing === "key"
+        ? `${command} needs SMOODLY_SECRET_KEY — the service-role key, or the cloud's write key. The publishable key sees published content only.`
+        : "This database has no Smoodly schema. Run `npx smoodly migrate`, then `supabase db push` (hosted) or `supabase db reset` (local).";
+}
+/** Every row of one table in one space, paged in primary-key order. The space filter is explicit: a service-role key sees every space. */
+export async function readSpaceRows(db, table, space, where = {}, columns = "*") {
+    const rows = [];
+    for (let from = 0;;) {
+        let q = db.from(table).select(columns).eq("space_id", space);
+        for (const [column, value] of Object.entries(where))
+            q = q.eq(column, value);
+        for (const column of ROW_KEY[table])
+            q = q.order(column);
+        const res = await q.range(from, from + PAGE_ROWS - 1);
+        if (res.error)
+            throw new Error(`smoodly: reading ${table}: ${res.error.message}`);
+        const page = (res.data ?? []);
+        if (page.length === 0)
+            return rows;
+        rows.push(...page);
+        from += page.length;
+    }
+}
+export const isNotFound = (e) => String(e.statusCode) === "404" || e.status === 404 || /not.?found/i.test(e.message);
+export const isAlreadyExists = (e) => String(e.statusCode) === "409" || e.status === 409 || /already exists/i.test(e.message);
+/** The installed package's version for the manifest: `../../package.json` from src/cli/ and dist/cli/ alike. */
+export function packageVersion() {
+    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+}

package/dist/space-transfer.d.ts

@@ -0,0 +1,58 @@
+import { type ContentTable } from "./sql-space.ts";
+/** The folder layout's own version, apart from the schema (spec §7). */
+export declare const FORMAT = 1;
+export type Row = Record<string, unknown>;
+export type TableRows = Record<ContentTable, Row[]>;
+export type ExportMember = {
+    email: string | null;
+    role: string;
+};
+export type Manifest = {
+    format: number;
+    schemaVersion: number;
+    smoodlyVersion: string;
+    exportedAt: string;
+    sourceSpace: string;
+    counts: Record<ContentTable, number>;
+    media: {
+        files: number;
+        bytes: number;
+        missing: string[];
+    };
+    members: ExportMember[];
+};
+/** Every foreign key's target lands before the row that names it (spec §9.3). */
+export declare const INSERT_ORDER: readonly ContentTable[];
+/** A row's identity inside one space: its primary key without `space_id`. */
+export declare const ROW_KEY: Record<ContentTable, readonly string[]>;
+/** The primary key as Postgres declares it — what "on conflict do nothing" names. */
+export declare const CONFLICT_COLUMNS: Record<ContentTable, string>;
+export declare const rowKey: (table: ContentTable, row: Row) => string;
+/** Sorted by key, so two exports of an unchanged space diff cleanly (spec §7). */
+export declare function sortRows(table: ContentTable, rows: Row[]): Row[];
+export declare const emptyTables: () => TableRows;
+/** A row as it leaves its space: no `space_id`; an asset's path without `<space>/`. */
+export declare function fromSpace(table: ContentTable, row: Row, space: string): Row;
+/** A row as it enters a space: `space_id` set; an asset's path prefixed. */
+export declare function intoSpace(table: ContentTable, row: Row, space: string): Row;
+/** Rows whose `column` names another row of the list come after it (parents, posters); a name outside the list counts as none. */
+export declare function referencedFirst(rows: Row[], column: string): Row[];
+/** The tables in insert order, their rows ordered for it (spec §9.3). */
+export declare function insertPlan(rows: TableRows): {
+    table: ContentTable;
+    rows: Row[];
+}[];
+/** The export's consistency check (spec §8.3): exactly the foreign keys the target enforces, one line per broken reference. */
+export declare function brokenReferences(rows: TableRows): string[];
+/** The import's target check (spec §9.1): per table, how many of the target's row keys this export does not hold. All zero = empty, or an earlier run. */
+export declare function foreignRows(target: Record<ContentTable, string[]>, exported: TableRows): Record<ContentTable, number>;
+export declare const countRows: (rows: TableRows) => Record<ContentTable, number>;
+export declare function formatBytes(n: number): string;
+/** "14 pages (41 versions), 32 entries (118 versions), 51 assets (38.2 MB), 9 redirects" (spec §8.5). */
+export declare function describeExport(rows: TableRows, bytes: number): string;
+/** "14 pages, 32 entries, 51 assets and 9 redirects" (spec §9.4). */
+export declare function describeImport(rows: TableRows): string;
+/** The target check's refusal (spec §9.1), naming only the tables that hold foreign rows. */
+export declare function notEmptyMessage(foreign: Record<ContentTable, number>): string;
+/** Spec §6: the target database's version must equal the export's. */
+export declare function versionMismatchMessage(target: number, exported: number): string;

package/dist/space-transfer.js

@@ -0,0 +1,174 @@
+// packages/smoodly/src/space-transfer.ts
+// The pure half of `smoodly export` / `smoodly import` (spec 2026-09-28
+// export/import): which tables travel, the order they land in, how a row
+// leaves its space and enters another, and the two checks — the export's
+// mirror of the target's foreign keys and the import's "only this
+// export's rows" test. No I/O; the CLI halves are cli/export.ts and
+// cli/import.ts.
+import { CONTENT_TABLES } from "./sql-space.js";
+/** The folder layout's own version, apart from the schema (spec §7). */
+export const FORMAT = 1;
+/** Every foreign key's target lands before the row that names it (spec §9.3). */
+export const INSERT_ORDER = [
+    "pages", "page_versions", "page_locales",
+    "entries", "entry_versions", "entry_locales",
+    "assets", "refs", "paths",
+];
+/** A row's identity inside one space: its primary key without `space_id`. */
+export const ROW_KEY = {
+    pages: ["id"],
+    page_locales: ["page_id", "locale"],
+    page_versions: ["id"],
+    entries: ["id"],
+    entry_locales: ["entry_id", "locale"],
+    entry_versions: ["id"],
+    refs: ["source_kind", "source_id", "source_field", "target_id"],
+    paths: ["locale", "path"],
+    assets: ["id"],
+};
+/** The primary key as Postgres declares it — what "on conflict do nothing" names. */
+export const CONFLICT_COLUMNS = Object.fromEntries(CONTENT_TABLES.map((t) => [t, (t === "paths" ? ["space_id", ...ROW_KEY[t]] : ROW_KEY[t]).join(",")]));
+export const rowKey = (table, row) => JSON.stringify(ROW_KEY[table].map((c) => row[c]));
+/** Sorted by key, so two exports of an unchanged space diff cleanly (spec §7). */
+export function sortRows(table, rows) {
+    return rows
+        .map((row) => [rowKey(table, row), row])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, row]) => row);
+}
+export const emptyTables = () => Object.fromEntries(CONTENT_TABLES.map((t) => [t, []]));
+/** A row as it leaves its space: no `space_id`; an asset's path without `<space>/`. */
+export function fromSpace(table, row, space) {
+    const { space_id: _space, ...rest } = row;
+    if (table !== "assets")
+        return rest;
+    const path = String(rest.path);
+    const prefix = `${space}/`;
+    if (!path.startsWith(prefix)) {
+        throw new Error(`smoodly: asset ${String(rest.id)} is stored at "${path}", outside its space's prefix "${prefix}".`);
+    }
+    return { ...rest, path: path.slice(prefix.length) };
+}
+/** A row as it enters a space: `space_id` set; an asset's path prefixed. */
+export function intoSpace(table, row, space) {
+    return table === "assets" ? { ...row, space_id: space, path: `${space}/${String(row.path)}` } : { ...row, space_id: space };
+}
+/** Rows whose `column` names another row of the list come after it (parents, posters); a name outside the list counts as none. */
+export function referencedFirst(rows, column) {
+    const ids = new Set(rows.map((r) => String(r.id)));
+    const placed = new Set();
+    const out = [];
+    let pending = rows;
+    while (pending.length > 0) {
+        const next = [];
+        for (const row of pending) {
+            const ref = row[column];
+            if (ref == null || !ids.has(String(ref)) || placed.has(String(ref))) {
+                out.push(row);
+                placed.add(String(row.id));
+            }
+            else
+                next.push(row);
+        }
+        if (next.length === pending.length)
+            throw new Error(`smoodly: a cycle in ${column} among ${next.length} rows.`);
+        pending = next;
+    }
+    return out;
+}
+/** The tables in insert order, their rows ordered for it (spec §9.3). */
+export function insertPlan(rows) {
+    return INSERT_ORDER.map((table) => ({
+        table,
+        rows: table === "pages" || table === "entries" ? referencedFirst(rows[table], "parent_id")
+            : table === "assets" ? referencedFirst(rows[table], "poster_id")
+                : rows[table],
+    }));
+}
+/** The export's consistency check (spec §8.3): exactly the foreign keys the target enforces, one line per broken reference. */
+export function brokenReferences(rows) {
+    const ids = (table) => new Set(rows[table].map((r) => String(r.id)));
+    const pages = ids("pages");
+    const entries = ids("entries");
+    const problems = [];
+    const check = (table, column, targets, targetTable) => {
+        for (const row of rows[table]) {
+            const ref = row[column];
+            if (ref != null && !targets.has(String(ref)))
+                problems.push(`${table} ${rowKey(table, row)}: ${column} ${String(ref)} is not in ${targetTable}`);
+        }
+    };
+    check("pages", "parent_id", pages, "pages");
+    check("page_versions", "page_id", pages, "pages");
+    check("page_locales", "page_id", pages, "pages");
+    check("page_locales", "draft_version_id", ids("page_versions"), "page_versions");
+    check("entries", "parent_id", entries, "entries");
+    check("entry_versions", "entry_id", entries, "entries");
+    check("entry_locales", "entry_id", entries, "entries");
+    check("entry_locales", "draft_version_id", ids("entry_versions"), "entry_versions");
+    check("assets", "poster_id", ids("assets"), "assets");
+    return problems;
+}
+/** The import's target check (spec §9.1): per table, how many of the target's row keys this export does not hold. All zero = empty, or an earlier run. */
+export function foreignRows(target, exported) {
+    return Object.fromEntries(CONTENT_TABLES.map((table) => {
+        const own = new Set(exported[table].map((row) => rowKey(table, row)));
+        return [table, target[table].filter((key) => !own.has(key)).length];
+    }));
+}
+export const countRows = (rows) => Object.fromEntries(CONTENT_TABLES.map((t) => [t, rows[t].length]));
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const listJoin = (items) => (items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`);
+const redirectCount = (rows) => rows.paths.filter((r) => r.redirect === true).length;
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+/** "14 pages (41 versions), 32 entries (118 versions), 51 assets (38.2 MB), 9 redirects" (spec §8.5). */
+export function describeExport(rows, bytes) {
+    return [
+        `${plural(rows.pages.length, "page")} (${plural(rows.page_versions.length, "version")})`,
+        `${plural(rows.entries.length, "entry", "entries")} (${plural(rows.entry_versions.length, "version")})`,
+        `${plural(rows.assets.length, "asset")} (${formatBytes(bytes)})`,
+        plural(redirectCount(rows), "redirect"),
+    ].join(", ");
+}
+/** "14 pages, 32 entries, 51 assets and 9 redirects" (spec §9.4). */
+export function describeImport(rows) {
+    return listJoin([
+        plural(rows.pages.length, "page"),
+        plural(rows.entries.length, "entry", "entries"),
+        plural(rows.assets.length, "asset"),
+        plural(redirectCount(rows), "redirect"),
+    ]);
+}
+const NOUN = {
+    pages: ["page", "pages"],
+    page_versions: ["page version", "page versions"],
+    page_locales: ["page locale row", "page locale rows"],
+    entries: ["entry", "entries"],
+    entry_versions: ["entry version", "entry versions"],
+    entry_locales: ["entry locale row", "entry locale rows"],
+    assets: ["asset", "assets"],
+    refs: ["reference row", "reference rows"],
+    paths: ["path row", "path rows"],
+};
+/** The target check's refusal (spec §9.1), naming only the tables that hold foreign rows. */
+export function notEmptyMessage(foreign) {
+    const parts = INSERT_ORDER.filter((t) => foreign[t] > 0).map((t) => plural(foreign[t], ...NOUN[t]));
+    return `The target space holds ${listJoin(parts)} that this export does not. Import needs an empty space: a new Supabase project, or \`supabase db reset\` on a local stack.`;
+}
+/** Spec §6: the target database's version must equal the export's. */
+export function versionMismatchMessage(target, exported) {
+    return target < exported
+        ? `The target database is at schema v${target} and this export is v${exported}: update smoodly to a version that ships v${exported}, run \`npx smoodly migrate\`, then \`supabase db push\`.`
+        : `The target database is at schema v${target}, newer than this export (v${exported}): migrate the source and export again.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoodly",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "Open-source, code-first CMS for Next.js on Supabase: define a component once, it becomes a typed, editable building block.",
   "license": "MIT",
   "repository": {