orionplace-react 0.1.0

package/src/project-readme.mjs

@@ -0,0 +1,341 @@
+export function projectReadme(settings, base = '') {
+  const frontend = settings.frontend || 'shop.example.com';
+  const backend  = settings.backend || 'https://your-project.orionplace.app/api';
+  return `# Your Orionplace React integration
+
+This folder contains the integration source for your Next.js 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.9 or newer (including npm). Run these commands from the folder
+where you want to create a new project; no existing Next.js project is needed:
+
+\`\`\`bash
+npx --yes orionplace-react init my-marketplace
+cd my-marketplace
+npm install
+npx orionplace-react set backend your-project.orionplace.app
+npx orionplace-react 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 Next.js (normally http://localhost:3000). 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-react set backend ${backend}
+npx orionplace-react add frontend ${frontend}
+npx orionplace-react add frontend www.${frontend}
+npx orionplace-react 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-react 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-react help
+npx orionplace-react 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 Next.js 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 Next.js 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. |
+| \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
+| \`../${base}proxy.ts\` | Marks personalized pages private and varies them by storefront domain. |
+| \`../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 layout, page or middleware.
+
+## 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()\` from
+\`${base}lib/orionplace/domain.ts\` when you build canonical URLs or page metadata.
+
+## Start and verify
+
+Use Node.js 20.9 or newer. After scaffolding a new project, install dependencies:
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+In another terminal:
+
+\`\`\`bash
+curl -i http://localhost:3000/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 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 |
+| --- | --- |
+| \`${base}app/layout.tsx\` | Awaits initialization, then passes the snapshot to the provider. |
+| \`${base}lib/orionplace/appLoadServer.ts\` | Server transport: one request per render through \`cache()\`. |
+| \`${base}lib/orionplace/appLoadClient.ts\` | Browser transport for explicit initialize and refresh. |
+| \`${base}lib/orionplace/appLoadResult.ts\` | HTTP, form-error and bootstrap-envelope checks. |
+| \`${base}lib/orionplace/domain.ts\` | The storefront domain selected for the current request. |
+| \`${base}stores/orionplace.ts\` | The typed snapshot, status, errors, merged discovery and selectors. |
+| \`${base}providers/OrionplaceProvider.tsx\` | One store per browser session, hydrated from the server snapshot. |
+| \`${base}hooks/useOrionplaceAppLoad.ts\` | Explicit initialize, refresh and reset actions. |
+| \`${base}interfaces/orionplace/index.ts\` | Response envelope and all nested models. |
+
+The server render owns initialization. Rendering a component or calling the hook
+never starts another request, and initialization never opens an authentication
+prompt.
+
+### Read data in a client component
+
+\`\`\`tsx
+'use client';
+
+import { useOrionplace } from '../providers/OrionplaceProvider';
+import { selectCurrencies, selectFailure, selectIsReady, selectProducts, selectStatus } from '../stores/orionplace';
+
+export function MarketplaceSummary() {
+  const isReady    = useOrionplace(selectIsReady);
+  const status     = useOrionplace(selectStatus);
+  const failure    = useOrionplace(selectFailure);
+  const products   = useOrionplace(selectProducts);
+  const currencies = useOrionplace(selectCurrencies);
+
+  if (failure) return <p role="alert">Marketplace initialization failed.</p>;
+  if (!isReady) return <p role="status">AppLoad: {status}</p>;
+  return <p>{products.length} products; {Object.keys(currencies).length} currencies.</p>;
+}
+\`\`\`
+
+Select one value at a time. Each selector returns a stable reference, so a
+component re-renders only when its own data changes. This example lives one
+directory below the project root, such as \`${base}components\`; adjust relative
+imports for deeper directories.
+
+| Selector | Available data |
+| --- | --- |
+| \`selectResult\` | Response envelope, HTTP status and load time. |
+| \`selectData\` | Complete \`page_data\`, including optional sections. |
+| \`selectInit\` | All initialization settings, banners, events, contacts, SEO, units and other sections. |
+| \`selectProfile\`, \`selectIsAuthenticated\` | Current profile and session state. |
+| \`selectLocales\`, \`selectCurrencies\`, \`selectCatalog\`, \`selectProducts\`, \`selectTariffs\` | Common initial collections. |
+| \`selectPublicEndpoints\`, \`selectAuthenticatedEndpoints\`, \`selectEndpoints\` | Current discovery groups and their combined view. |
+| \`selectIsReady\`, \`selectStatus\`, \`selectFailure\` | Readiness, loading/success/error state and sanitized failure details. |
+
+Use \`selectEndpoint(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 component
+
+\`\`\`tsx
+import { getOrionplaceAppLoad } from '../lib/orionplace/appLoadServer';
+
+export default async function CatalogPage() {
+  const { result, failure } = await getOrionplaceAppLoad();
+  if (failure || !result) return <p role="alert">Marketplace initialization failed.</p>;
+  const categories = result.response.page_data.init.catalog ?? [];
+  return <p>{categories.length} catalog roots.</p>;
+}
+\`\`\`
+
+\`getOrionplaceAppLoad()\` is cached per render, so the layout and your page share
+one request. Do not import it from a client component.
+
+### Refresh after a session change
+
+\`\`\`tsx
+'use client';
+
+import { useOrionplaceAppLoad } from '../hooks/useOrionplaceAppLoad';
+
+export function SessionActions() {
+  const { reset, refresh } = useOrionplaceAppLoad();
+  async function afterSessionChanged() {
+    reset();
+    await refresh();
+  }
+  return <button type="button" onClick={() => void 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.
+
+### 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.
+
+The server render forwards the incoming request's cookies and domain to the same
+gateway, in process. React Server Components cannot write response cookies, so a
+new backend cookie from that render is not relayed to the browser: the browser
+establishes and updates its own session through \`/api/...\` requests. The raw
+\`Set-Cookie\` headers are available as \`cookies\` from \`requestAppLoad()\` if you
+relay them from your own route handler or server action. New response cookies
+never update the current render's request. 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/react#session-cookies)
+
+### Rendering, navigation and failures
+
+Each server render gets its own request-scoped snapshot; the provider 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 \`selectIsReady\` before using required data.
+
+Page responses use \`private, no-store\` through \`${base}proxy.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-react 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-react/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-react 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 does not support static export or edge-only hosting. 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
+HOSTNAME=127.0.0.1 PORT=3000 node --env-file=.env node_modules/next/dist/bin/next start
+\`\`\`
+
+The production process explicitly reads \`MIMIC_FRONT_DOMAIN\`. A public domain
+still takes precedence. The Node port must stay private behind your HTTPS proxy.
+
+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
+
+- [React package installation and domain setup](https://orionmarket.place/sandbox/new-project/react)
+- [AppLoad](https://orionmarket.place/sandbox)
+`;
+}

package/src/setup.mjs

@@ -0,0 +1,250 @@
+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 untouched instead of failing.
+const optional = ['app/layout.tsx', 'app/page.tsx', 'app/page.module.css', 'app/globals.css', 'proxy.ts'];
+
+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 nextConfigTemplate = `import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;
+`;
+const tsconfigTemplate = {
+  compilerOptions: {
+    target: 'ES2022', lib: ['dom', 'dom.iterable', 'esnext'], allowJs: true, skipLibCheck: true,
+    strict: true, noEmit: true, esModuleInterop: true, module: 'esnext', moduleResolution: 'bundler',
+    resolveJsonModule: true, isolatedModules: true, jsx: 'react-jsx', incremental: true,
+    plugins: [{ name: 'next' }], paths: { '@/*': ['./*'] },
+  },
+  include: ['next-env.d.ts', '**/*.ts', '**/*.tsx', '.next/types/**/*.ts', '.next/dev/types/**/*.ts'],
+  exclude: ['node_modules'],
+};
+/**
+ * Next.js needs no plugin registration: the gateway is a route handler in the
+ * project. Only a conflicting /api rewrite or redirect must be resolved first.
+ */
+function inspectNextConfig(source) {
+  const cleaned = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+  if (/\b(?:rewrites|redirects)\b/.test(cleaned) && /source\s*:\s*['"`]\/api(?:\/|['"`])/.test(cleaned)) {
+    throw new Error('Remove the conflicting /api rewrite or redirect from the Next.js configuration: Orionplace handles API routing. No files were changed.');
+  }
+  if (/\boutput\s*:\s*['"`]export['"`]/.test(cleaned)) {
+    throw new Error('Static export cannot read domain files. Use the default Node.js server output. 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', 'next.config.ts', 'next.config.js', 'next.config.mjs', 'orionplace/settings.json', 'orionplace/.generated.json', '.env', '.gitignore'];
+  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' };
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  if (action === 'update' && (!dependencies.next || !current['orionplace/settings.json'] || !current['orionplace/.generated.json'])) {
+    throw new Error('Update requires an initialized Orionplace React project. Run init first.');
+  }
+  if (!dependencies.next && ['nuxt', '@sveltejs/kit'].some(name => dependencies[name])) throw new Error('This package sets up Next.js projects only.');
+  if (dependencies.next && !/^(?:[~^]|>=)?16(?:\.|$)/.test(dependencies.next)) {
+    throw new Error('This release supports Next.js 16. Upgrade your Next.js dependency before setup.');
+  }
+  const configs = ['next.config.ts', 'next.config.js', 'next.config.mjs'].filter(name => current[name] !== null);
+  if (configs.length > 1) throw new Error('Multiple Next.js configuration files found; keep one root config.');
+  const configName = configs[0] || 'next.config.ts';
+  if (configs.length) inspectNextConfig(current[configName]);
+  // The App Router lives in app/ or src/app/; generated source follows it.
+  const base       = await directoryExists(root, 'src/app') || (!await directoryExists(root, 'app') && await directoryExists(root, 'src')) ? 'src/' : '';
+  if (await directoryExists(root, `${base}pages`)) {
+    throw new Error('This release generates App Router source. Remove or migrate the Pages Router directory first.');
+  }
+  for (const directory of [`${base}app/api`, `${base}pages/api`]) {
+    const path  = await safePath(root, directory);
+    let entries = [];
+    try { entries = await readdir(path); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (entries.some(name => name.startsWith('[...') && name !== '[...orionplace]')) {
+      throw new Error(`Existing API catch-all in ${directory}. 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 = [];
+  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 isNewNext                             = !dependencies.next;
+  if (!configs.length) await plan(configName, nextConfigTemplate, { managed: true, preserve: true });
+  pkg.scripts                               ||= {};
+  pkg.scripts.dev                           ||= 'next dev';
+  pkg.scripts.build                         ||= 'next build';
+  pkg.scripts.start                         ||= 'next start';
+  pkg.scripts['orionplace:backend']         ||= 'orionplace-react set backend';
+  pkg.scripts['orionplace:frontend']        ||= 'orionplace-react set frontend';
+  pkg.scripts['orionplace:add-frontend']    ||= 'orionplace-react add frontend';
+  pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-react remove frontend';
+  pkg.scripts['orionplace:mimic']           ||= 'orionplace-react set mimic';
+  pkg.scripts['orionplace:help']            ||= 'orionplace-react help';
+  pkg.scripts['orionplace:update']          ||= 'orionplace-react update';
+  pkg.dependencies                          ||= {};
+  pkg.dependencies.zustand                  ||= dependencies.zustand || '^5.0.15';
+  pkg.dependencies['orionplace-react']      ||= dependencies['orionplace-react'] || `^${metadata.version}`;
+  if (action === 'update') {
+    pkg.dependencies['orionplace-react'] = metadata.version;
+    if (pkg.devDependencies) delete pkg.devDependencies['orionplace-react'];
+  }
+  if (isNewNext) {
+    pkg.dependencies.next                    = '^16.3.4';
+    pkg.dependencies.react                 ||= '^19.3.0';
+    pkg.dependencies['react-dom']          ||= '^19.3.0';
+    pkg.devDependencies                    ||= {};
+    pkg.devDependencies.typescript         ||= '^5.9.3';
+    pkg.devDependencies['@types/node']     ||= '^22.18.0';
+    pkg.devDependencies['@types/react']    ||= '^19.3.0';
+    pkg.devDependencies['@types/react-dom'] ||= '^19.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; }
+      const target = base + name;
+      // Never replace a customer's own layout, page, styles or middleware.
+      if (optional.includes(name) && !previous[target] && await read(await safePath(root, target)) !== null) continue;
+      const source = (await readFile(new URL(name, templateRoot), 'utf8'))
+        .replaceAll('__ORIONPLACE_RUNTIME__', runtimeImport(target));
+      await plan(target, 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, base), { 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/', '.next/', 'out/', 'next-env.d.ts', '.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, dryRun, isNewNext, base };
+}

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 React release…');
+    await npm(['exec', '--yes', '--prefer-online', '--package=orionplace-react@latest', '--',
+      'orionplace-react', '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`;
+}