create-shapio 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shapio",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold a new Shapio project (npx create-shapio my-cms) or a site starter (--site astro|next|sveltekit)",
   "license": "Apache-2.0",
   "homepage": "https://shapio.dev",

package/templates/astro/package.json

@@ -19,8 +19,8 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@shapio/client": "^0.2.1",
-    "@shapio/visual": "^0.2.1",
+    "@shapio/client": "^0.3.0",
+    "@shapio/visual": "^0.3.0",
     "astro": "7.3.5"
   },
   "devDependencies": {

package/templates/astro/scripts/lib/admin.ts

@@ -3,10 +3,13 @@ import { createClient, type ShapioClient } from '@shapio/client';
 /**
  * How the seed talks to Shapio's admin API: with SHAPIO_TOKEN (an admin API token), or with
  * SHAPIO_ADMIN_EMAIL + SHAPIO_ADMIN_PASSWORD, in which case it signs in, creates a one-hour admin API token
- * for itself (the schema CLI needs a bearer token) and revokes it when done.
+ * for itself (the schema CLI needs a bearer token) and revokes it when done. Every request is about the site
+ * in SHAPIO_SITE (the one the starter reads), else the token's site, else the primary site.
  */
 export type AdminConnection = {
   url: string;
+  /** SHAPIO_SITE, if set: the site every request is about. */
+  site: string | undefined;
   token: string;
   client: ShapioClient;
   /** A signed-in admin session (email and password only): preview tokens are issued to people, not API tokens. */
@@ -17,7 +20,7 @@ export type AdminConnection = {
 const SESSION_COOKIE = 'shapio_session';
 const SEED_TOKEN_TTL_MS = 60 * 60 * 1000;
 
-const signIn = async (url: string, email: string, password: string) => {
+const signIn = async (url: string, email: string, password: string, site: string | undefined) => {
   const response = await fetch(`${url.replace(/\/+$/, '')}/api/admin/auth/login`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -34,16 +37,20 @@ const signIn = async (url: string, email: string, password: string) => {
   return createClient({
     baseUrl: url,
     headers: () => ({ cookie: cookie.split(';')[0] ?? '', 'x-csrf-token': csrfToken }),
+    ...(site ? { site } : {}),
   });
 };
 
 export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnection> => {
   const url = env.SHAPIO_URL ?? 'http://localhost:4300';
+  const site = env.SHAPIO_SITE?.trim() || undefined;
+  const siteOption = site ? { site } : {};
   if (env.SHAPIO_TOKEN) {
     return {
       url,
+      site,
       token: env.SHAPIO_TOKEN,
-      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN }),
+      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN, ...siteOption }),
       session: undefined,
       close: async () => undefined,
     };
@@ -53,7 +60,7 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   if (!email || !password) {
     throw new Error('Set SHAPIO_TOKEN (an admin API token), or SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD');
   }
-  const session = await signIn(url, email, password);
+  const session = await signIn(url, email, password, site);
   const roles = await session.admin.roles.list();
   const admin = roles.find((role) => role.key === 'admin');
   if (!admin) {
@@ -68,8 +75,9 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   });
   return {
     url,
+    site,
     token: created.token,
-    client: createClient({ baseUrl: url, token: created.token }),
+    client: createClient({ baseUrl: url, token: created.token, ...siteOption }),
     session,
     close: () => session.admin.tokens.revoke(created.apiToken.id),
   };

package/templates/astro/scripts/seed.ts

@@ -27,7 +27,8 @@ import { createPng } from './lib/png.js';
  * content to the seed):
  * 1. the `fr` locale;
  * 2. the models and components in shapio/ through the schema apply API (live, no restart; the same planner
- *    as `shapio schema apply` and the admin);
+ *    as `shapio schema apply` and the admin), as the site's own (SHAPIO_SITE, else the token's site, else the
+ *    primary): a starter's schema belongs to the first site it is seeded on;
  * 3. placeholder images, an author, the site settings, pages and articles in English and French, published
  *    per locale;
  * 4. a deployment connection named "Preview" whose preview URL opens this starter's /preview/ page (the
@@ -64,7 +65,12 @@ const MEDIA_READY_TIMEOUT_MS = 120_000;
 const SCHEMA_CHANGE_TIMEOUT_MS = 120_000;
 const POLL_INTERVAL_MS = 500;
 /** No lock file: a first apply. Definitions that already match are skipped by the server. */
-const FIRST_APPLY_BASE: SchemaApplyInput['base'] = { formatVersion: 1, schemaVersion: 0, definitions: {} };
+const FIRST_APPLY_BASE: SchemaApplyInput['base'] = {
+  formatVersion: 2,
+  schemaVersion: 0,
+  sites: [],
+  definitions: {},
+};
 
 const log = (line: string) => process.stdout.write(`${line}\n`);
 
@@ -106,15 +112,43 @@ const waitForChange = async (client: ShapioClient, item: SchemaSyncResult) => {
   }
 };
 
+/** A refusal the seed explains itself: printed without a stack. */
+class SeedRefusedError extends Error {}
+
+/** The schema files' IDs already belong to another site's definitions (the starter was seeded there first). */
+const isSeededElsewhere = (error: unknown) =>
+  error instanceof ShapioApiError &&
+  error.code === 'SCHEMA_INVALID' &&
+  ((error.details as { issues?: Array<{ code?: string }> } | undefined)?.issues ?? []).some(
+    (issue) => issue.code === 'DUPLICATE_ID',
+  );
+
 const applySchema = async (client: ShapioClient) => {
-  const response = await client.admin.schema.apply({
-    definitions: await readDefinitions(),
-    base: FIRST_APPLY_BASE,
-    prune: false,
-    dryRun: false,
-    acknowledgeBreaking: false,
-    acknowledgeDestructive: false,
-  });
+  const definitions = await readDefinitions();
+  let response;
+  try {
+    response = await client.admin.schema.apply({
+      definitions,
+      // Every definition is the site's own (sites/<key>/ in a pulled tree), never shared by default.
+      scopes: definitions.map(() => 'site' as const),
+      base: FIRST_APPLY_BASE,
+      prune: false,
+      dryRun: false,
+      acknowledgeBreaking: false,
+      acknowledgeDestructive: false,
+    });
+  } catch (error) {
+    if (isSeededElsewhere(error)) {
+      throw new SeedRefusedError(
+        "This starter's schema already belongs to another site of this instance: a starter's schema belongs " +
+          'to the first site it is seeded on. To reuse it on this site, share it with all sites ' +
+          'with a network admin token (`shapio schema scope <apiKey> --shared --site <that site>` for each ' +
+          'component, then author, page, article and siteSettings) and seed again, or seed a separate instance.',
+        { cause: error },
+      );
+    }
+    throw error;
+  }
   for (const item of response.results) {
     if (item.outcome === 'pending') {
       await waitForChange(client, item);
@@ -347,17 +381,24 @@ const tryRevalidateWebhook = async (client: ShapioClient, siteUrl: string, path:
   }
 };
 
-const writeEnv = async (url: string, deliveryToken: string, webhookSecret: string | undefined) => {
+const writeEnv = async (
+  url: string,
+  site: string | undefined,
+  deliveryToken: string,
+  webhookSecret: string | undefined,
+) => {
   const path = resolve('.env');
   const lines = [
     '# Written by the seed. The delivery token is read-only; keep this file out of git.',
     `SHAPIO_URL=${url}`,
     `SHAPIO_DELIVERY_TOKEN=${deliveryToken}`,
+    // The site the content was seeded on: the starter reads the same one.
+    ...(site ? [`SHAPIO_SITE=${site}`] : []),
     ...(webhookSecret ? [`SHAPIO_WEBHOOK_SECRET=${webhookSecret}`] : []),
   ];
   await writeFile(path, `${lines.join('\n')}\n`, { mode: 0o600 });
   log(
-    `Wrote SHAPIO_URL, SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
+    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
   );
 };
 
@@ -381,16 +422,24 @@ const main = async () => {
     const webhookSecret = revalidatePath
       ? await tryRevalidateWebhook(admin.client, siteUrl, revalidatePath)
       : undefined;
-    await writeEnv(admin.url, await createDeliveryToken(admin.client), webhookSecret);
+    await writeEnv(admin.url, admin.site, await createDeliveryToken(admin.client), webhookSecret);
     log('Seeded. Build the site with: npm run build');
   } finally {
     await admin.close();
   }
 };
 
+const describeFailure = (error: unknown) => {
+  if (error instanceof SeedRefusedError) {
+    return error.message;
+  }
+  if (error instanceof ShapioApiError) {
+    return `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}`;
+  }
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+};
+
 main().catch((error: unknown) => {
-  process.stderr.write(
-    `seed failed: ${error instanceof ShapioApiError ? `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}` : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
-  );
+  process.stderr.write(`seed failed: ${describeFailure(error)}\n`);
   process.exitCode = 1;
 });

package/templates/next/package.json

@@ -17,8 +17,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.2.1",
-    "@shapio/visual": "^0.2.1",
+    "@shapio/client": "^0.3.0",
+    "@shapio/visual": "^0.3.0",
     "next": "16.3.8",
     "react": "19.3.0",
     "react-dom": "19.3.0"

package/templates/next/scripts/lib/admin.ts

@@ -3,10 +3,13 @@ import { createClient, type ShapioClient } from '@shapio/client';
 /**
  * How the seed talks to Shapio's admin API: with SHAPIO_TOKEN (an admin API token), or with
  * SHAPIO_ADMIN_EMAIL + SHAPIO_ADMIN_PASSWORD, in which case it signs in, creates a one-hour admin API token
- * for itself (the schema CLI needs a bearer token) and revokes it when done.
+ * for itself (the schema CLI needs a bearer token) and revokes it when done. Every request is about the site
+ * in SHAPIO_SITE (the one the starter reads), else the token's site, else the primary site.
  */
 export type AdminConnection = {
   url: string;
+  /** SHAPIO_SITE, if set: the site every request is about. */
+  site: string | undefined;
   token: string;
   client: ShapioClient;
   /** A signed-in admin session (email and password only): preview tokens are issued to people, not API tokens. */
@@ -17,7 +20,7 @@ export type AdminConnection = {
 const SESSION_COOKIE = 'shapio_session';
 const SEED_TOKEN_TTL_MS = 60 * 60 * 1000;
 
-const signIn = async (url: string, email: string, password: string) => {
+const signIn = async (url: string, email: string, password: string, site: string | undefined) => {
   const response = await fetch(`${url.replace(/\/+$/, '')}/api/admin/auth/login`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -34,16 +37,20 @@ const signIn = async (url: string, email: string, password: string) => {
   return createClient({
     baseUrl: url,
     headers: () => ({ cookie: cookie.split(';')[0] ?? '', 'x-csrf-token': csrfToken }),
+    ...(site ? { site } : {}),
   });
 };
 
 export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnection> => {
   const url = env.SHAPIO_URL ?? 'http://localhost:4300';
+  const site = env.SHAPIO_SITE?.trim() || undefined;
+  const siteOption = site ? { site } : {};
   if (env.SHAPIO_TOKEN) {
     return {
       url,
+      site,
       token: env.SHAPIO_TOKEN,
-      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN }),
+      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN, ...siteOption }),
       session: undefined,
       close: async () => undefined,
     };
@@ -53,7 +60,7 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   if (!email || !password) {
     throw new Error('Set SHAPIO_TOKEN (an admin API token), or SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD');
   }
-  const session = await signIn(url, email, password);
+  const session = await signIn(url, email, password, site);
   const roles = await session.admin.roles.list();
   const admin = roles.find((role) => role.key === 'admin');
   if (!admin) {
@@ -68,8 +75,9 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   });
   return {
     url,
+    site,
     token: created.token,
-    client: createClient({ baseUrl: url, token: created.token }),
+    client: createClient({ baseUrl: url, token: created.token, ...siteOption }),
     session,
     close: () => session.admin.tokens.revoke(created.apiToken.id),
   };

package/templates/next/scripts/seed.ts

@@ -27,7 +27,8 @@ import { createPng } from './lib/png.js';
  * content to the seed):
  * 1. the `fr` locale;
  * 2. the models and components in shapio/ through the schema apply API (live, no restart; the same planner
- *    as `shapio schema apply` and the admin);
+ *    as `shapio schema apply` and the admin), as the site's own (SHAPIO_SITE, else the token's site, else the
+ *    primary): a starter's schema belongs to the first site it is seeded on;
  * 3. placeholder images, an author, the site settings, pages and articles in English and French, published
  *    per locale;
  * 4. a deployment connection named "Preview" whose preview URL opens this starter's /preview/ page (the
@@ -64,7 +65,12 @@ const MEDIA_READY_TIMEOUT_MS = 120_000;
 const SCHEMA_CHANGE_TIMEOUT_MS = 120_000;
 const POLL_INTERVAL_MS = 500;
 /** No lock file: a first apply. Definitions that already match are skipped by the server. */
-const FIRST_APPLY_BASE: SchemaApplyInput['base'] = { formatVersion: 1, schemaVersion: 0, definitions: {} };
+const FIRST_APPLY_BASE: SchemaApplyInput['base'] = {
+  formatVersion: 2,
+  schemaVersion: 0,
+  sites: [],
+  definitions: {},
+};
 
 const log = (line: string) => process.stdout.write(`${line}\n`);
 
@@ -106,15 +112,43 @@ const waitForChange = async (client: ShapioClient, item: SchemaSyncResult) => {
   }
 };
 
+/** A refusal the seed explains itself: printed without a stack. */
+class SeedRefusedError extends Error {}
+
+/** The schema files' IDs already belong to another site's definitions (the starter was seeded there first). */
+const isSeededElsewhere = (error: unknown) =>
+  error instanceof ShapioApiError &&
+  error.code === 'SCHEMA_INVALID' &&
+  ((error.details as { issues?: Array<{ code?: string }> } | undefined)?.issues ?? []).some(
+    (issue) => issue.code === 'DUPLICATE_ID',
+  );
+
 const applySchema = async (client: ShapioClient) => {
-  const response = await client.admin.schema.apply({
-    definitions: await readDefinitions(),
-    base: FIRST_APPLY_BASE,
-    prune: false,
-    dryRun: false,
-    acknowledgeBreaking: false,
-    acknowledgeDestructive: false,
-  });
+  const definitions = await readDefinitions();
+  let response;
+  try {
+    response = await client.admin.schema.apply({
+      definitions,
+      // Every definition is the site's own (sites/<key>/ in a pulled tree), never shared by default.
+      scopes: definitions.map(() => 'site' as const),
+      base: FIRST_APPLY_BASE,
+      prune: false,
+      dryRun: false,
+      acknowledgeBreaking: false,
+      acknowledgeDestructive: false,
+    });
+  } catch (error) {
+    if (isSeededElsewhere(error)) {
+      throw new SeedRefusedError(
+        "This starter's schema already belongs to another site of this instance: a starter's schema belongs " +
+          'to the first site it is seeded on. To reuse it on this site, share it with all sites ' +
+          'with a network admin token (`shapio schema scope <apiKey> --shared --site <that site>` for each ' +
+          'component, then author, page, article and siteSettings) and seed again, or seed a separate instance.',
+        { cause: error },
+      );
+    }
+    throw error;
+  }
   for (const item of response.results) {
     if (item.outcome === 'pending') {
       await waitForChange(client, item);
@@ -347,17 +381,24 @@ const tryRevalidateWebhook = async (client: ShapioClient, siteUrl: string, path:
   }
 };
 
-const writeEnv = async (url: string, deliveryToken: string, webhookSecret: string | undefined) => {
+const writeEnv = async (
+  url: string,
+  site: string | undefined,
+  deliveryToken: string,
+  webhookSecret: string | undefined,
+) => {
   const path = resolve('.env');
   const lines = [
     '# Written by the seed. The delivery token is read-only; keep this file out of git.',
     `SHAPIO_URL=${url}`,
     `SHAPIO_DELIVERY_TOKEN=${deliveryToken}`,
+    // The site the content was seeded on: the starter reads the same one.
+    ...(site ? [`SHAPIO_SITE=${site}`] : []),
     ...(webhookSecret ? [`SHAPIO_WEBHOOK_SECRET=${webhookSecret}`] : []),
   ];
   await writeFile(path, `${lines.join('\n')}\n`, { mode: 0o600 });
   log(
-    `Wrote SHAPIO_URL, SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
+    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
   );
 };
 
@@ -381,16 +422,24 @@ const main = async () => {
     const webhookSecret = revalidatePath
       ? await tryRevalidateWebhook(admin.client, siteUrl, revalidatePath)
       : undefined;
-    await writeEnv(admin.url, await createDeliveryToken(admin.client), webhookSecret);
+    await writeEnv(admin.url, admin.site, await createDeliveryToken(admin.client), webhookSecret);
     log('Seeded. Build the site with: npm run build');
   } finally {
     await admin.close();
   }
 };
 
+const describeFailure = (error: unknown) => {
+  if (error instanceof SeedRefusedError) {
+    return error.message;
+  }
+  if (error instanceof ShapioApiError) {
+    return `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}`;
+  }
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+};
+
 main().catch((error: unknown) => {
-  process.stderr.write(
-    `seed failed: ${error instanceof ShapioApiError ? `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}` : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
-  );
+  process.stderr.write(`seed failed: ${describeFailure(error)}\n`);
   process.exitCode = 1;
 });

package/templates/sveltekit/package.json

@@ -21,8 +21,8 @@
     "typecheck": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings"
   },
   "dependencies": {
-    "@shapio/client": "^0.2.1",
-    "@shapio/visual": "^0.2.1"
+    "@shapio/client": "^0.3.0",
+    "@shapio/visual": "^0.3.0"
   },
   "devDependencies": {
     "@sveltejs/adapter-static": "4.0.0",

package/templates/sveltekit/scripts/lib/admin.ts

@@ -3,10 +3,13 @@ import { createClient, type ShapioClient } from '@shapio/client';
 /**
  * How the seed talks to Shapio's admin API: with SHAPIO_TOKEN (an admin API token), or with
  * SHAPIO_ADMIN_EMAIL + SHAPIO_ADMIN_PASSWORD, in which case it signs in, creates a one-hour admin API token
- * for itself (the schema CLI needs a bearer token) and revokes it when done.
+ * for itself (the schema CLI needs a bearer token) and revokes it when done. Every request is about the site
+ * in SHAPIO_SITE (the one the starter reads), else the token's site, else the primary site.
  */
 export type AdminConnection = {
   url: string;
+  /** SHAPIO_SITE, if set: the site every request is about. */
+  site: string | undefined;
   token: string;
   client: ShapioClient;
   /** A signed-in admin session (email and password only): preview tokens are issued to people, not API tokens. */
@@ -17,7 +20,7 @@ export type AdminConnection = {
 const SESSION_COOKIE = 'shapio_session';
 const SEED_TOKEN_TTL_MS = 60 * 60 * 1000;
 
-const signIn = async (url: string, email: string, password: string) => {
+const signIn = async (url: string, email: string, password: string, site: string | undefined) => {
   const response = await fetch(`${url.replace(/\/+$/, '')}/api/admin/auth/login`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -34,16 +37,20 @@ const signIn = async (url: string, email: string, password: string) => {
   return createClient({
     baseUrl: url,
     headers: () => ({ cookie: cookie.split(';')[0] ?? '', 'x-csrf-token': csrfToken }),
+    ...(site ? { site } : {}),
   });
 };
 
 export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnection> => {
   const url = env.SHAPIO_URL ?? 'http://localhost:4300';
+  const site = env.SHAPIO_SITE?.trim() || undefined;
+  const siteOption = site ? { site } : {};
   if (env.SHAPIO_TOKEN) {
     return {
       url,
+      site,
       token: env.SHAPIO_TOKEN,
-      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN }),
+      client: createClient({ baseUrl: url, token: env.SHAPIO_TOKEN, ...siteOption }),
       session: undefined,
       close: async () => undefined,
     };
@@ -53,7 +60,7 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   if (!email || !password) {
     throw new Error('Set SHAPIO_TOKEN (an admin API token), or SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD');
   }
-  const session = await signIn(url, email, password);
+  const session = await signIn(url, email, password, site);
   const roles = await session.admin.roles.list();
   const admin = roles.find((role) => role.key === 'admin');
   if (!admin) {
@@ -68,8 +75,9 @@ export const connectAdmin = async (env: NodeJS.ProcessEnv): Promise<AdminConnect
   });
   return {
     url,
+    site,
     token: created.token,
-    client: createClient({ baseUrl: url, token: created.token }),
+    client: createClient({ baseUrl: url, token: created.token, ...siteOption }),
     session,
     close: () => session.admin.tokens.revoke(created.apiToken.id),
   };

package/templates/sveltekit/scripts/seed.ts

@@ -27,7 +27,8 @@ import { createPng } from './lib/png.js';
  * content to the seed):
  * 1. the `fr` locale;
  * 2. the models and components in shapio/ through the schema apply API (live, no restart; the same planner
- *    as `shapio schema apply` and the admin);
+ *    as `shapio schema apply` and the admin), as the site's own (SHAPIO_SITE, else the token's site, else the
+ *    primary): a starter's schema belongs to the first site it is seeded on;
  * 3. placeholder images, an author, the site settings, pages and articles in English and French, published
  *    per locale;
  * 4. a deployment connection named "Preview" whose preview URL opens this starter's /preview/ page (the
@@ -64,7 +65,12 @@ const MEDIA_READY_TIMEOUT_MS = 120_000;
 const SCHEMA_CHANGE_TIMEOUT_MS = 120_000;
 const POLL_INTERVAL_MS = 500;
 /** No lock file: a first apply. Definitions that already match are skipped by the server. */
-const FIRST_APPLY_BASE: SchemaApplyInput['base'] = { formatVersion: 1, schemaVersion: 0, definitions: {} };
+const FIRST_APPLY_BASE: SchemaApplyInput['base'] = {
+  formatVersion: 2,
+  schemaVersion: 0,
+  sites: [],
+  definitions: {},
+};
 
 const log = (line: string) => process.stdout.write(`${line}\n`);
 
@@ -106,15 +112,43 @@ const waitForChange = async (client: ShapioClient, item: SchemaSyncResult) => {
   }
 };
 
+/** A refusal the seed explains itself: printed without a stack. */
+class SeedRefusedError extends Error {}
+
+/** The schema files' IDs already belong to another site's definitions (the starter was seeded there first). */
+const isSeededElsewhere = (error: unknown) =>
+  error instanceof ShapioApiError &&
+  error.code === 'SCHEMA_INVALID' &&
+  ((error.details as { issues?: Array<{ code?: string }> } | undefined)?.issues ?? []).some(
+    (issue) => issue.code === 'DUPLICATE_ID',
+  );
+
 const applySchema = async (client: ShapioClient) => {
-  const response = await client.admin.schema.apply({
-    definitions: await readDefinitions(),
-    base: FIRST_APPLY_BASE,
-    prune: false,
-    dryRun: false,
-    acknowledgeBreaking: false,
-    acknowledgeDestructive: false,
-  });
+  const definitions = await readDefinitions();
+  let response;
+  try {
+    response = await client.admin.schema.apply({
+      definitions,
+      // Every definition is the site's own (sites/<key>/ in a pulled tree), never shared by default.
+      scopes: definitions.map(() => 'site' as const),
+      base: FIRST_APPLY_BASE,
+      prune: false,
+      dryRun: false,
+      acknowledgeBreaking: false,
+      acknowledgeDestructive: false,
+    });
+  } catch (error) {
+    if (isSeededElsewhere(error)) {
+      throw new SeedRefusedError(
+        "This starter's schema already belongs to another site of this instance: a starter's schema belongs " +
+          'to the first site it is seeded on. To reuse it on this site, share it with all sites ' +
+          'with a network admin token (`shapio schema scope <apiKey> --shared --site <that site>` for each ' +
+          'component, then author, page, article and siteSettings) and seed again, or seed a separate instance.',
+        { cause: error },
+      );
+    }
+    throw error;
+  }
   for (const item of response.results) {
     if (item.outcome === 'pending') {
       await waitForChange(client, item);
@@ -347,17 +381,24 @@ const tryRevalidateWebhook = async (client: ShapioClient, siteUrl: string, path:
   }
 };
 
-const writeEnv = async (url: string, deliveryToken: string, webhookSecret: string | undefined) => {
+const writeEnv = async (
+  url: string,
+  site: string | undefined,
+  deliveryToken: string,
+  webhookSecret: string | undefined,
+) => {
   const path = resolve('.env');
   const lines = [
     '# Written by the seed. The delivery token is read-only; keep this file out of git.',
     `SHAPIO_URL=${url}`,
     `SHAPIO_DELIVERY_TOKEN=${deliveryToken}`,
+    // The site the content was seeded on: the starter reads the same one.
+    ...(site ? [`SHAPIO_SITE=${site}`] : []),
     ...(webhookSecret ? [`SHAPIO_WEBHOOK_SECRET=${webhookSecret}`] : []),
   ];
   await writeFile(path, `${lines.join('\n')}\n`, { mode: 0o600 });
   log(
-    `Wrote SHAPIO_URL, SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
+    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
   );
 };
 
@@ -381,16 +422,24 @@ const main = async () => {
     const webhookSecret = revalidatePath
       ? await tryRevalidateWebhook(admin.client, siteUrl, revalidatePath)
       : undefined;
-    await writeEnv(admin.url, await createDeliveryToken(admin.client), webhookSecret);
+    await writeEnv(admin.url, admin.site, await createDeliveryToken(admin.client), webhookSecret);
     log('Seeded. Build the site with: npm run build');
   } finally {
     await admin.close();
   }
 };
 
+const describeFailure = (error: unknown) => {
+  if (error instanceof SeedRefusedError) {
+    return error.message;
+  }
+  if (error instanceof ShapioApiError) {
+    return `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}`;
+  }
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+};
+
 main().catch((error: unknown) => {
-  process.stderr.write(
-    `seed failed: ${error instanceof ShapioApiError ? `${error.code}: ${error.message} ${JSON.stringify(error.details ?? '')}` : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
-  );
+  process.stderr.write(`seed failed: ${describeFailure(error)}\n`);
   process.exitCode = 1;
 });