orionplace-svelte 0.1.0

package/src/project-readme.mjs

@@ -0,0 +1,341 @@
+export function projectReadme(settings) {
+  const frontend = settings.frontend || 'shop.example.com';
+  const backend  = settings.backend || 'https://your-project.orionplace.app/api';
+  return `# Your Orionplace SvelteKit integration
+
+This folder contains the integration source for your SvelteKit storefront.
+Your personal backend API is provided in your account at https://orionmarket.place.
+You can change that backend domain in your account, then update this project.
+
+## Quick start from zero
+
+Install Node.js 20.19 or newer (including npm). Run these commands from the folder
+where you want to create a new project; no existing SvelteKit project is needed:
+
+\`\`\`bash
+npx --yes orionplace-svelte init my-marketplace
+cd my-marketplace
+npm install
+npx orionplace-svelte set backend your-project.orionplace.app
+npx orionplace-svelte add frontend shop.example.com
+npm run dev
+\`\`\`
+
+Replace \`your-project.orionplace.app\` with the personal backend domain shown in
+your profile at [orionmarket.place](https://orionmarket.place), and
+\`shop.example.com\` with your storefront domain. The first frontend also becomes
+the local MIMIC domain.
+
+Open the local URL printed by Vite (normally http://localhost:5173). The starter
+should show \`Loaded\` in its AppLoad state section. If it shows \`Failed\`, check
+the domain mapping and backend response before building pages.
+
+This project is already generated. To configure or run it, use the following
+sections from its root directory; do not create another project inside it.
+
+## Current setup
+
+- Frontend domains: ${settings.frontends?.length ? settings.frontends.map(domain => '\`' + domain + '\`').join(', ') : 'not configured yet'}
+- Local MIMIC domain: \`${settings.frontend || 'empty'}\`
+- Personal API: \`${settings.backend || 'not configured yet'}\`
+
+Set or change these values from the project root:
+
+\`\`\`bash
+npx orionplace-svelte set backend ${backend}
+npx orionplace-svelte add frontend ${frontend}
+npx orionplace-svelte add frontend www.${frontend}
+npx orionplace-svelte remove frontend www.${frontend}
+\`\`\`
+
+Set the backend or add a frontend first; either order works. Each frontend has its
+own \`sitemaps/<domain>.cfg\` mapping to your personal API. Adding a domain again
+is safe. Changing the backend updates every CLI-managed frontend mapping.
+
+MIMIC is empty in a new project: \`MIMIC_FRONT_DOMAIN=""\`. Setting the backend
+alone leaves it empty. The first added frontend sets MIMIC; adding more domains
+preserves that choice.
+
+Use \`npx orionplace-svelte set mimic <domain>\` to select an already-added frontend
+for localhost. It changes MIMIC without editing domain mappings. Add an unknown
+domain with \`add frontend\` first. The legacy \`set frontend\` shortcut still
+adds and selects a frontend.
+
+\`\`\`bash
+npx orionplace-svelte help
+npx orionplace-svelte set mimic ${frontend}
+\`\`\`
+
+Removing a frontend deletes only its unchanged generated \`.cfg\` file. If it was
+the selected MIMIC domain, the first remaining domain takes its place. Removing
+the last frontend clears MIMIC; add a frontend again before making API requests.
+Unknown or manually edited mappings are not removed automatically.
+
+Restart a running development server after changing domains so Vite reloads its
+allowed hosts and SvelteKit reloads \`.env\`. Production reads domain files on each
+request; restart or reload the process environment when changing MIMIC. DNS, TLS
+and hosting-proxy settings must also cover each public frontend domain.
+Existing unrelated environment variables and SvelteKit configuration are preserved.
+
+## Files you can read and customize
+
+| File | Purpose |
+| --- | --- |
+| \`runtime/marketplace.mjs\` | Domain lookup, configuration validation, API transport and cookies. |
+| \`runtime/marketplace.d.mts\` | Types for the gateway functions used by your TypeScript source. |
+| \`settings.json\` | The CLI's frontend list, local MIMIC domain and personal backend; not a secret store. |
+| \`../src/routes/api/[...orionplace]/+server.ts\` | The route serving \`/api/...\` from your project. |
+| \`../src/hooks.server.ts\` | Marks personalized pages private and varies them by storefront domain. |
+| \`../svelte.config.js\` | Uses \`@sveltejs/adapter-node\`, which this integration requires. |
+| \`../vite.config.ts\` | Allows your storefront domains during local development. |
+| \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
+| \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
+
+You can edit these files; subsequent setup runs preserve customized source and
+this README. The CLI refuses to overwrite an unknown or manually changed domain
+mapping, and never replaces your own configuration, layout, page or hooks. When it
+keeps one of your files, it prints the path so you can merge the starter yourself.
+
+## How requests reach your personal API
+
+The trusted hosting proxy supplies the public domain through \`X-Front-Domain\`,
+\`X-Forwarded-Host\`, or \`Host\`, in that order. On localhost,
+\`MIMIC_FRONT_DOMAIN\` supplies the domain instead. A known public domain takes
+priority over MIMIC; an unconfigured public domain returns \`503\`.
+
+The domain file is read for each request. The gateway preserves the request method,
+query, body, authorization and cookies. Backend HTTP status codes are preserved.
+Backend cookie domains are removed so cookies belong to the active frontend.
+Responses are not cached by this gateway. Network failures return \`502\`.
+
+The configuration directory defaults to \`sitemaps\` under the process working
+directory. Set \`SITEMAPS_DIR\` only if you store it elsewhere. Nothing here sets
+a fixed public site URL. Use \`getStorefrontDomain(event.request)\` from
+\`src/lib/orionplace/domain.ts\` when you build canonical URLs or page metadata.
+
+## Start and verify
+
+Use Node.js 20.19 or newer. After scaffolding a new project, install dependencies:
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+In another terminal:
+
+\`\`\`bash
+curl -i http://localhost:5173/api/appload \\
+  -H 'Content-Type: application/json' \\
+  --data '{"ignore_cache":true,"detalize_mode":"light"}'
+\`\`\`
+
+Check both the HTTP status and \`form_errors\`. Successful initialization returns
+\`page_data\`; HTTP 200 by itself is insufficient. Documentation and public requests
+do not require a login prompt. Protected actions still require backend permission.
+
+## AppLoad architecture
+
+The root layout load initializes the marketplace before your page renders. The
+request uses \`POST /api/appload\` with \`detalize_mode: "light"\` and
+\`ignore_cache: true\`. Tenant settings may override these options.
+
+| Project file | Responsibility |
+| --- | --- |
+| \`src/routes/+layout.server.ts\` | Awaits initialization and returns the snapshot to every route. |
+| \`src/routes/+layout.svelte\` | Creates the store for this session and puts it in context. |
+| \`src/lib/orionplace/appLoadServer.ts\` | Server transport, session forwarding and response-cookie relay. |
+| \`src/lib/orionplace/appLoadClient.ts\` | Browser transport for explicit initialize and refresh. |
+| \`src/lib/orionplace/appLoadResult.ts\` | HTTP, form-error and bootstrap-envelope checks. |
+| \`src/lib/orionplace/appLoadData.ts\` | Discovery merging and snapshot status, without reactivity. |
+| \`src/lib/orionplace/store.svelte.ts\` | The typed snapshot, status, errors and derived data as Svelte 5 runes. |
+| \`src/lib/orionplace/domain.ts\` | The storefront domain selected for the current request. |
+| \`src/lib/interfaces/orionplace/index.ts\` | Response envelope and all nested models. |
+
+The server render owns initialization. Reading the store never starts a request,
+and initialization never opens an authentication prompt.
+
+### Read data in a component
+
+\`\`\`svelte
+<script lang="ts">
+	import { getOrionplaceContext } from '$lib/orionplace/store.svelte';
+
+	const marketplace = getOrionplaceContext();
+</script>
+
+{#if marketplace.failure}
+	<p role="alert">Marketplace initialization failed.</p>
+{:else if !marketplace.isReady}
+	<p role="status">AppLoad: {marketplace.status}</p>
+{:else}
+	<p>{marketplace.products.length} products; {Object.keys(marketplace.currencies).length} currencies.</p>
+{/if}
+\`\`\`
+
+The store is reactive: reading a property inside markup or an effect re-renders
+that part when the data changes.
+
+| Store property | Available data |
+| --- | --- |
+| \`result\` | Response envelope, HTTP status and load time. |
+| \`data\` | Complete \`page_data\`, including optional sections. |
+| \`init\` | All initialization settings, banners, events, contacts, SEO, units and other sections. |
+| \`profile\`, \`isAuthenticated\` | Current profile and session state. |
+| \`locales\`, \`currencies\`, \`catalog\`, \`products\`, \`tariffs\` | Common initial collections. |
+| \`publicEndpoints\`, \`authenticatedEndpoints\`, \`endpoints\` | Current discovery groups and their combined view. |
+| \`isReady\`, \`status\`, \`failure\` | Readiness, loading/success/error state and sanitized failure details. |
+
+Use \`marketplace.getEndpoint(section, name)\` with section and endpoint keys from
+the current response. It returns the endpoint's target, methods and forms, or
+\`undefined\` when unavailable. Full descriptions may be omitted in light mode.
+Discovery describes availability; the backend checks permissions on every call.
+
+### Read data in a server load
+
+\`\`\`typescript
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ parent }) => {
+	const { orionplace } = await parent();
+	const categories     = orionplace.result?.response.page_data.init.catalog ?? [];
+	return { categories };
+};
+\`\`\`
+
+The layout load already made the request; \`await parent()\` reuses its snapshot
+instead of calling AppLoad again.
+
+### Refresh after a session change
+
+\`\`\`svelte
+<script lang="ts">
+	import { getOrionplaceContext } from '$lib/orionplace/store.svelte';
+
+	const marketplace = getOrionplaceContext();
+
+	async function afterSessionChanged() {
+		marketplace.reset();
+		await marketplace.refresh();
+	}
+</script>
+
+<button type="button" onclick={afterSessionChanged}>Reload marketplace</button>
+\`\`\`
+
+Call this after the session-changing API request has completed. Reset clears the
+profile, initialization and discovery, aborts pending initialization and prevents
+late responses restoring the old session. Refresh replaces the whole snapshot.
+On failure, stale data and permissions remain cleared; the store exposes the error.
+SvelteKit's \`invalidateAll()\` also works: the layout load runs again and the
+store adopts the new server snapshot.
+
+### Session and CSRF cookies
+
+Session and CSRF cookies travel in HTTP headers, not in the initialization JSON.
+Keep the signed HttpOnly \`sessionid\` opaque: the browser sends it automatically.
+Never log, decode, rewrite or put cookie values in the store or localStorage.
+Read the current \`csrftoken\` for each protected browser action and send it as
+\`X-CSRFToken\` through the same-origin \`/api/\` gateway with credentials enabled.
+Login can rotate the token. The AppLoad loaders handle initialization; they are
+not a general CSRF-aware client for other endpoints.
+
+During a server render the layout load forwards the incoming cookies and relays
+each backend \`Set-Cookie\` separately through SvelteKit's cookie API, preserving
+the exact signed value and attributes. The gateway removed only the backend
+\`Domain\`, so those cookies belong to your storefront. Cookies established this
+way are also visible to later calls in the same render. Never share a cookie jar
+across visitors.
+
+Renew CSRF using \`POST /api/csrf_renew\` with \`{}\`, then re-read the cookie.
+HTTP \`419\` with \`page_data.csrf: false\` means CSRF rejection; a general
+\`403\` can mean permissions or origin rejection. Offer explicit retries for
+mutations. After confirmed login/logout, reset and refresh AppLoad; these actions
+change application data and do not log in/out or delete cookies.
+
+[Cookie lifecycle and browser request example](https://orionmarket.place/sandbox/appload/svelte#session-cookies)
+
+### Rendering, navigation and failures
+
+Each server render gets its own snapshot; the layout creates one store per browser
+session and hydrates it, so hydration and client navigation do not repeat
+initialization. Concurrent \`load\` calls share one request per store.
+
+Failures also survive hydration and navigation. They never open a login modal or
+trigger an automatic retry on every route. Show the error and offer explicit
+reload. Feature components should check \`isReady\` before using required data.
+
+Page responses use \`private, no-store\` through \`src/hooks.server.ts\`. Do not put
+personalized HTML in shared caches or persist the snapshot in localStorage. The
+debug page displays summaries; account details, keys and backend exception stacks
+are not rendered there.
+
+Interfaces cover initialization, discovery/forms, profile and nested models.
+Plugin-defined configuration uses JSON types; interfaces are not full runtime
+validation of every nested field. Existing edited generated source is preserved;
+review and merge newer templates manually where the CLI reports preserved files.
+
+## Update the package and components
+
+Run this from your project root whenever you want the latest release:
+
+\`\`\`bash
+npx orionplace-svelte update
+\`\`\`
+
+The command fetches the latest CLI, adds new template files, refreshes unchanged
+generated source, updates the package dependency, and runs \`npm install\`.
+It preserves edited files and lists them for manual review. Find their incoming
+versions under \`node_modules/orionplace-svelte/templates\` or \`runtime\`.
+Domain mappings, domain settings and \`.env\` are preserved. Upstream file removals
+do not delete local source. Restart development or rebuild and redeploy afterward.
+
+Use \`npx orionplace-svelte update --dry-run\` to review changes without modifying
+project files or installed dependencies; downloading the CLI may update npm's
+cache. The alias \`npm run orionplace:update\` performs the same normal update.
+If installation fails after source generation, run \`npm install\` and retry.
+
+## Deploy on your VPS
+
+This integration needs a Node.js server and its domain configuration files.
+It uses \`@sveltejs/adapter-node\`; static and edge-only adapters cannot read
+domain files. Deploy the build, dependencies, \`sitemaps\`, and your environment
+configuration together; use an absolute \`SITEMAPS_DIR\` when running from another
+working directory.
+
+\`\`\`bash
+npm run build
+HOST=127.0.0.1 PORT=3000 node --env-file=.env build/index.js
+\`\`\`
+
+The production process explicitly reads \`MIMIC_FRONT_DOMAIN\`. A public domain
+still takes precedence. The Node port must stay private behind your HTTPS proxy.
+Set \`ORIGIN\`, or \`PROTOCOL_HEADER\` and \`HOST_HEADER\`, as the adapter's
+documentation describes, so SvelteKit trusts your proxy's forwarded headers.
+
+Inside the storefront's HTTPS Nginx server block:
+
+\`\`\`nginx
+location / {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Front-Domain $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Init-Ip $remote_addr;
+    proxy_buffering off;
+}
+\`\`\`
+
+Here localhost is your frontend process on your VPS. That process selects the
+remote personal API from the domain file. The proxy must overwrite those headers.
+An unknown domain never falls back to another tenant. This setup does not generate
+sitemap XML or add analytics.
+
+## More documentation
+
+- [SvelteKit package installation and domain setup](https://orionmarket.place/sandbox/new-project/svelte)
+- [AppLoad](https://orionmarket.place/sandbox)
+`;
+}

package/src/setup.mjs

@@ -0,0 +1,261 @@
+import { readFile, readdir, lstat, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import { resolve, dirname, relative, sep, posix } from 'node:path';
+import { createHash } from 'node:crypto';
+import { backendUrl, frontendDomain } from './validation.mjs';
+import { projectReadme } from './project-readme.mjs';
+
+const metadata     = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const hash         = text => createHash('sha256').update(text).digest('hex');
+// Generated files a customer may already own: keep theirs and report them instead of failing.
+const optional     = [
+  'svelte.config.js', 'vite.config.ts', 'src/app.html', 'src/app.d.ts', 'src/hooks.server.ts',
+  'src/routes/+layout.server.ts', 'src/routes/+layout.svelte', 'src/routes/+page.svelte',
+];
+// One template covers each of these project files, whatever extension the project uses.
+const equivalents  = {
+  'svelte.config.js': ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'],
+  'vite.config.ts': ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'],
+  'src/hooks.server.ts': ['src/hooks.server.ts', 'src/hooks.server.js'],
+  'src/routes/+layout.server.ts': ['src/routes/+layout.server.ts', 'src/routes/+layout.server.js'],
+};
+const otherAdapter = /@sveltejs\/adapter-(auto|static|vercel|netlify|cloudflare|cloudflare-workers|deno)/;
+
+async function read(path) {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function safePath(root, name) {
+  const target = resolve(root, name);
+  if (relative(root, target).startsWith('..') || target === root) throw new Error('Invalid generated path');
+  let cursor = root;
+  for (const piece of relative(root, target).split(sep)) {
+    cursor = resolve(cursor, piece);
+    try { if ((await lstat(cursor)).isSymbolicLink()) throw new Error(`Refusing symbolic link: ${name}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return target;
+}
+async function directoryExists(root, name) {
+  try { return (await lstat(resolve(root, name))).isDirectory(); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+/** Generated source imports the editable gateway by an explicit relative path. */
+function runtimeImport(name) {
+  const from = posix.dirname(name);
+  const path = posix.relative(from, 'orionplace/runtime/marketplace.mjs');
+  return path.startsWith('.') ? path : `./${path}`;
+}
+const tsconfigTemplate = {
+  extends: './.svelte-kit/tsconfig.json',
+  compilerOptions: {
+    allowJs: true, checkJs: false, esModuleInterop: true, forceConsistentCasingInFileNames: true,
+    resolveJsonModule: true, skipLibCheck: true, sourceMap: true, strict: true, moduleResolution: 'bundler',
+  },
+};
+/**
+ * SvelteKit needs no plugin registration: the gateway is a route in the project.
+ * Only a non-Node adapter or a conflicting /api rewrite must be resolved first.
+ */
+function inspectSvelteConfig(source) {
+  const cleaned = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+  if (otherAdapter.test(cleaned)) {
+    throw new Error('The marketplace gateway reads domain files from disk. Switch svelte.config.js to @sveltejs/adapter-node before setup. No files were changed.');
+  }
+  if (/\b(?:appDir|files\s*:)/.test(cleaned) && /routes\s*:/.test(cleaned)) {
+    throw new Error('Custom SvelteKit directories require manual integration. No files were changed.');
+  }
+}
+function updateEnvironment(source, domain) {
+  const lines  = (source || '').split(/\r?\n/);
+  let updated  = false;
+  const result = lines.flatMap(line => {
+    if (!/^\s*(?:export\s+)?MIMIC_FRONT_DOMAIN\s*=/.test(line)) return [line];
+    if (updated) return [];
+    updated = true;
+    return [`MIMIC_FRONT_DOMAIN="${domain}"`];
+  });
+  if (!updated) result.push(`MIMIC_FRONT_DOMAIN="${domain}"`);
+  return result.join('\n').replace(/^\n/, '').replace(/\n*$/, '\n');
+}
+
+export async function setupProject({ cwd = process.cwd(), action = 'set', field, value, dryRun = false } = {}) {
+  if (!['set', 'add', 'remove', 'update'].includes(action) ||
+      (['add', 'remove'].includes(action) && field !== 'frontend') || (action === 'update' && field)) {
+    throw new Error('Use set backend, add frontend, remove frontend, set mimic, or set frontend.');
+  }
+  const root    = resolve(cwd);
+  const setting = field === 'backend' ? backendUrl(value) : ['frontend', 'mimic'].includes(field) ? frontendDomain(value) : null;
+  if (field && !setting) throw new Error('Choose backend, frontend, or mimic.');
+  const names   = ['package.json', 'orionplace/settings.json', 'orionplace/.generated.json', '.env', '.gitignore',
+    ...equivalents['svelte.config.js'], ...equivalents['vite.config.ts']];
+  const current = {};
+  for (const name of names) current[name] = await read(await safePath(root, name));
+  const pkg          = current['package.json'] ? JSON.parse(current['package.json']) : { name: 'orionplace-storefront', private: true, version: '0.1.0', type: 'module' };
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  const kit          = dependencies['@sveltejs/kit'];
+  if (action === 'update' && (!kit || !current['orionplace/settings.json'] || !current['orionplace/.generated.json'])) {
+    throw new Error('Update requires an initialized Orionplace Svelte project. Run init first.');
+  }
+  if (!kit && ['nuxt', 'next'].some(name => dependencies[name])) throw new Error('This package sets up SvelteKit projects only.');
+  if (kit && !/^(?:[~^]|>=)?2(?:\.|$)/.test(kit)) {
+    throw new Error('This release supports SvelteKit 2. Upgrade your @sveltejs/kit dependency before setup.');
+  }
+  if (kit && dependencies.svelte && !/^(?:[~^]|>=)?5(?:\.|$)/.test(dependencies.svelte)) {
+    throw new Error('The generated starter uses Svelte 5 runes. Upgrade your svelte dependency before setup.');
+  }
+  const configs = equivalents['svelte.config.js'].filter(name => current[name] !== null);
+  if (configs.length > 1) throw new Error('Multiple Svelte configuration files found; keep one root config.');
+  if (configs.length) inspectSvelteConfig(current[configs[0]]);
+  for (const name of Object.keys(dependencies)) {
+    if (otherAdapter.test(name)) {
+      throw new Error(`Remove ${name} and use @sveltejs/adapter-node: the gateway reads domain files from disk. No files were changed.`);
+    }
+  }
+  if (await directoryExists(root, 'src/routes/api')) {
+    const entries = await readdir(await safePath(root, 'src/routes/api'));
+    if (entries.some(name => name.startsWith('[...') && name !== '[...orionplace]')) {
+      throw new Error('Existing API catch-all in src/routes/api. Resolve this route conflict first.');
+    }
+  }
+  const settings = current['orionplace/settings.json'] ? JSON.parse(current['orionplace/settings.json']) : {};
+  const previous = current['orionplace/.generated.json'] ? JSON.parse(current['orionplace/.generated.json']) : {};
+  if (settings.backend) settings.backend = backendUrl(settings.backend);
+  if (settings.frontend) settings.frontend = frontendDomain(settings.frontend);
+  const oldFrontend = settings.frontend;
+  const frontends   = settings.frontends ?? (settings.frontend ? [settings.frontend] : []);
+  if (!Array.isArray(frontends)) throw new Error('settings.frontends must be an array of domain names.');
+  settings.frontends = [...new Set(frontends.map(frontendDomain))];
+  if (settings.frontend && !settings.frontends.includes(settings.frontend)) settings.frontends.unshift(settings.frontend);
+  if (field === 'backend') settings.backend = setting;
+  if (field === 'mimic') {
+    if (!settings.frontends.includes(setting)) {
+      throw new Error(`Add this frontend before selecting it for MIMIC: ${setting}`);
+    }
+    settings.frontend = setting;
+  }
+  if (field === 'frontend') {
+    if (action === 'remove') {
+      if (!settings.frontends.includes(setting)) throw new Error(`Frontend is not managed by this project: ${setting}`);
+      settings.frontends = settings.frontends.filter(domain => domain !== setting);
+      if (settings.frontend === setting) settings.frontend = settings.frontends[0];
+    } else {
+      if (!settings.frontends.includes(setting)) settings.frontends.push(setting);
+      // Adding an alias preserves the local development domain. "set" selects it.
+      if (action === 'set' || !settings.frontend) settings.frontend = setting;
+    }
+  }
+  settings.frontend ||= settings.frontends[0];
+  if (!settings.frontend) delete settings.frontend;
+  const manifest  = { ...previous };
+  const changes   = new Map();
+  const preserved = [];
+  const skipped   = [];
+  async function plan(name, content, { managed = false, preserve = false } = {}) {
+    const path     = await safePath(root, name);
+    const existing = await read(path);
+    if (managed && existing !== null && existing !== content && previous[name] !== hash(existing)) {
+      if (preserve && previous[name]) { preserved.push(name); return; }
+      throw new Error(`Refusing to overwrite ${name}: it is not an unchanged generated file. No files were changed.`);
+    }
+    if (existing !== content) changes.set(name, content);
+    if (managed) manifest[name] = hash(content);
+  }
+  async function planRemoval(name) {
+    const existing = await read(await safePath(root, name));
+    if (existing !== null && previous[name] !== hash(existing)) {
+      throw new Error(`Refusing to remove ${name}: it is not an unchanged generated file. No files were changed.`);
+    }
+    if (existing !== null) changes.set(name, null);
+    delete manifest[name];
+  }
+  // All checks and content generation happen before the first write.
+  const isNewKit                              = !kit;
+  pkg.type                                  ||= 'module';
+  pkg.scripts                               ||= {};
+  pkg.scripts.dev                           ||= 'vite dev';
+  pkg.scripts.build                         ||= 'vite build';
+  pkg.scripts.preview                       ||= 'vite preview';
+  pkg.scripts.prepare                       ||= 'svelte-kit sync || echo ""';
+  pkg.scripts.check                         ||= 'svelte-kit sync && svelte-check --tsconfig ./tsconfig.json';
+  pkg.scripts['orionplace:backend']         ||= 'orionplace-svelte set backend';
+  pkg.scripts['orionplace:frontend']        ||= 'orionplace-svelte set frontend';
+  pkg.scripts['orionplace:add-frontend']    ||= 'orionplace-svelte add frontend';
+  pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-svelte remove frontend';
+  pkg.scripts['orionplace:mimic']           ||= 'orionplace-svelte set mimic';
+  pkg.scripts['orionplace:help']            ||= 'orionplace-svelte help';
+  pkg.scripts['orionplace:update']          ||= 'orionplace-svelte update';
+  pkg.dependencies                          ||= {};
+  pkg.dependencies['orionplace-svelte']     ||= dependencies['orionplace-svelte'] || `^${metadata.version}`;
+  pkg.devDependencies                       ||= {};
+  pkg.devDependencies['@sveltejs/adapter-node'] ||= dependencies['@sveltejs/adapter-node'] || '^5.5.7';
+  // The generated Vite configuration reads the domain directory through Node APIs.
+  pkg.devDependencies['@types/node']            ||= dependencies['@types/node'] || '^22.18.0';
+  if (action === 'update') {
+    pkg.dependencies['orionplace-svelte'] = metadata.version;
+    if (pkg.devDependencies) delete pkg.devDependencies['orionplace-svelte'];
+  }
+  if (isNewKit) {
+    pkg.devDependencies['@sveltejs/kit']                = '^2.70.3';
+    pkg.devDependencies['@sveltejs/vite-plugin-svelte'] = '^7.3.0';
+    pkg.devDependencies.svelte                        ||= '^5.57.0';
+    pkg.devDependencies['svelte-check']               ||= '^4.7.6';
+    pkg.devDependencies.typescript                    ||= '^5.9.3';
+    pkg.devDependencies.vite                          ||= '^8.3.0';
+  }
+  const templateRoot = new URL('../templates/', import.meta.url);
+  async function planTemplates(directory = '') {
+    for (const entry of await readdir(new URL(directory, templateRoot), { withFileTypes: true })) {
+      const name = directory + entry.name;
+      if (entry.isDirectory()) { await planTemplates(name + '/'); continue; }
+      if (optional.includes(name) && !previous[name]) {
+        // Never replace a customer's own configuration, layout, page or hooks.
+        const existing = await Promise.all((equivalents[name] ?? [name])
+          .map(async variant => await read(await safePath(root, variant)) !== null ? variant : null));
+        const owned    = existing.find(Boolean);
+        if (owned) { skipped.push(owned); continue; }
+      }
+      const source = (await readFile(new URL(name, templateRoot), 'utf8'))
+        .replaceAll('__ORIONPLACE_RUNTIME__', runtimeImport(name));
+      await plan(name, source, { managed: true, preserve: true });
+    }
+  }
+  await planTemplates();
+  if (!await read(await safePath(root, 'tsconfig.json'))) {
+    await plan('tsconfig.json', JSON.stringify(tsconfigTemplate, null, 2) + '\n', { managed: true });
+  }
+  await plan('package.json', JSON.stringify(pkg, null, 2) + '\n');
+  await plan('orionplace/runtime/marketplace.mjs', await readFile(new URL('../runtime/marketplace.mjs', import.meta.url), 'utf8'), { managed: true, preserve: true });
+  await plan('orionplace/runtime/marketplace.d.mts', await readFile(new URL('../runtime/marketplace.d.mts', import.meta.url), 'utf8'), { managed: true, preserve: true });
+  await plan('orionplace/README.md', projectReadme(settings), { managed: true, preserve: true });
+  // A new project starts explicitly empty; keep a pre-existing manual setting on init.
+  const hasMimicSetting = /^\s*(?:export\s+)?MIMIC_FRONT_DOMAIN\s*=/m.test(current['.env'] || '');
+  if (action !== 'update' && (settings.frontend || oldFrontend || !hasMimicSetting)) {
+    await plan('.env', updateEnvironment(current['.env'], settings.frontend || ''));
+  }
+  if (settings.backend && action !== 'update') {
+    const mappings = action === 'remove' || field === 'mimic' ? []
+      : field === 'frontend' ? [setting] : settings.frontends;
+    for (const domain of mappings) {
+      await plan(`sitemaps/${domain}.cfg`, settings.backend + '\n', { managed: true });
+    }
+  }
+  if (action === 'remove') await planRemoval(`sitemaps/${setting}.cfg`);
+  let ignore = current['.gitignore'] || '';
+  for (const entry of ['node_modules/', '.svelte-kit/', 'build/', '.env', '.env.*', '!.env.example']) {
+    if (!ignore.split(/\r?\n/).includes(entry)) ignore = ignore.replace(/\n*$/, '\n') + entry + '\n';
+  }
+  await plan('.gitignore', ignore);
+  if (action !== 'update') await plan('orionplace/settings.json', JSON.stringify(settings, null, 2) + '\n');
+  await plan('orionplace/.generated.json', JSON.stringify(manifest, null, 2) + '\n');
+  if (!dryRun) {
+    for (const [name, content] of changes) {
+      const target = await safePath(root, name);
+      if (content === null) { await unlink(target); continue; }
+      await mkdir(dirname(target), { recursive: true });
+      const temporary = `${target}.orionplace-${process.pid}.tmp`;
+      await writeFile(temporary, content, { mode: name === '.env' ? 0o600 : 0o644, flag: 'wx' });
+      await rename(temporary, target);
+    }
+  }
+  return { root, settings, changed: [...changes.keys()], removed: [...changes].filter(([, content]) => content === null).map(([name]) => name), preserved, skipped, dryRun, isNewKit };
+}

package/src/update.mjs

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { setupProject } from './setup.mjs';
+
+export function runNpm(args, cwd) {
+  const npmCli      = process.env.npm_execpath;
+  const command     = npmCli ? process.execPath : 'npm';
+  const commandArgs = npmCli ? [npmCli, ...args] : args;
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, commandArgs, { cwd, stdio: 'inherit', shell: false });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(
+      `npm ${args[0]} failed (${signal || code}).`,
+    )));
+  });
+}
+
+export async function updateProject({ cwd = process.cwd(), dryRun = false, local = false, npm = runNpm } = {}) {
+  cwd = resolve(cwd);
+  // Validate before downloading or writing; the latest CLI repeats preflight with its own templates.
+  const preview = await setupProject({ cwd, action: 'update', dryRun: true });
+  if (!local) {
+    console.log('Checking the latest Orionplace Svelte release…');
+    await npm(['exec', '--yes', '--prefer-online', '--package=orionplace-svelte@latest', '--',
+      'orionplace-svelte', 'update', '--local', '--cwd', cwd, ...(dryRun ? ['--dry-run'] : [])], cwd);
+    return null; // The latest CLI reports its own changes.
+  }
+  if (dryRun) return preview;
+  const result = await setupProject({ cwd, action: 'update' });
+  try {
+    await npm(['install', '--no-audit', '--no-fund'], cwd);
+  } catch (error) {
+    throw new Error(`Source files were updated, but dependency installation failed. Run npm install in the project, then retry update. ${error.message}`);
+  }
+  return result;
+}

package/src/validation.mjs

@@ -0,0 +1,27 @@
+import { isIP } from 'node:net';
+const dns = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export function frontendDomain(value) {
+  let url;
+  try { url = new URL(value.includes('://') ? value : `https://${value}`); }
+  catch { throw new Error('Use a public frontend hostname, for example shop.example.com.'); }
+  const domain = url.hostname.toLowerCase().replace(/\.$/, '');
+  if (!dns.test(domain) || isIP(domain) || url.username || url.password || url.port ||
+      url.search || url.hash || url.pathname !== '/' || !['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Frontend must be a public hostname without a port, path, or credentials.');
+  }
+  return domain;
+}
+
+export function backendUrl(value) {
+  let url;
+  try { url = new URL(value.includes('://') ? value : `https://${value}`); }
+  catch { throw new Error('Use the personal backend domain shown in your Orionplace account.'); }
+  const path = url.pathname.replace(/\/+$/, '');
+  if (url.protocol !== 'https:' || !dns.test(url.hostname) ||
+      !url.hostname.endsWith('.orionplace.app') || url.username || url.password ||
+      url.port || url.search || url.hash || !['', '/api'].includes(path)) {
+    throw new Error('Backend must be https://<your-project>.orionplace.app or its /api URL.');
+  }
+  return `${url.origin}/api`;
+}