orionplace-nuxt 0.1.1 → 0.1.3

package/README.md

@@ -62,12 +62,13 @@ to inspect planned changes without writing them.
 
 ```bash
 npx orionplace-nuxt init [directory]
+npx orionplace-nuxt update
 npx orionplace-nuxt set backend your-project.orionplace.app
 npx orionplace-nuxt add frontend shop.example.com
 npx orionplace-nuxt add frontend www.shop.example.com
 npx orionplace-nuxt remove frontend www.shop.example.com
-npx orionplace-nuxt set frontend shop.example.com
-npx orionplace-nuxt --help
+npx orionplace-nuxt set mimic shop.example.com
+npx orionplace-nuxt help
 ```
 
 Either domain command can run first. Both settings are needed for a usable mapping.
@@ -77,6 +78,9 @@ After setup, these npm script aliases are also available:
 npm run orionplace:backend -- your-project.orionplace.app
 npm run orionplace:add-frontend -- shop.example.com
 npm run orionplace:remove-frontend -- www.shop.example.com
+npm run orionplace:mimic -- shop.example.com
+npm run orionplace:help
+npm run orionplace:update
 ```
 
 `npm set` belongs to npm's own configuration system; use the commands above.
@@ -100,7 +104,7 @@ change your account, create DNS records, configure TLS, or deploy a VPS.
 The module executes the generated local runtime files. You can read and customize
 them. Later setup runs preserve edited runtime files and the project README,
 reporting which files were preserved. Unchanged generated files can be refreshed
-by running `init` after upgrading the package. A manually edited domain file is
+with `npx orionplace-nuxt update`. A manually edited domain file is
 never silently overwritten. Keep the hash manifest in version control.
 
 ## Multiple frontend domains
@@ -109,9 +113,14 @@ Each frontend gets its own `sitemaps/<domain>.cfg`. `add frontend` preserves oth
 domains and can be repeated safely. `set backend` updates every CLI-managed mapping
 to the new personal API; it refuses to overwrite a manually edited mapping.
 
-The first added frontend becomes `MIMIC_FRONT_DOMAIN` in `.env`. Further additions
-preserve that local development choice. `set frontend <domain>` adds the domain
-if needed and selects it for MIMIC; it does not remove other domains.
+A new project starts with `MIMIC_FRONT_DOMAIN=""` in `.env`. Setting a backend
+alone leaves it empty. The first added frontend becomes MIMIC; further additions
+preserve that choice. `set mimic <domain>` selects an already-added frontend and
+updates MIMIC without changing any domain mappings. Unknown domains are rejected;
+add them with `add frontend` first.
+
+`help`, `--help`, and `-h` display commands without writing files. The legacy
+`set frontend <domain>` shortcut remains supported: it adds and selects a domain.
 
 `remove frontend <domain>` removes that domain from the list and deletes only its
 unchanged generated `.cfg`. Removing the MIMIC domain selects the first remaining
@@ -167,4 +176,52 @@ npm pack --dry-run
 ```
 
 The published tarball includes only the CLI, module, runtime source, README,
-license, and package metadata.
+license, starter templates, and package metadata.
+
+## AppLoad starter
+
+The CLI generates an AppLoad debug `app/app.vue`, an SSR-aware
+`useOrionplaceAppLoad()` composable, validation helpers and the full nested
+TypeScript contract under `app/interfaces/orionplace/`. The first page loads
+`POST /api/appload`, shows request state and section counts, and supports reload.
+It preserves custom apps and edited generated files. Generated instructions in
+`orionplace/README.md` explain how to integrate the composable in an existing app.
+
+## Update an existing project
+
+After the initial setup, use one command to get the latest package and components:
+
+```bash
+npx orionplace-nuxt update
+```
+
+It runs the latest CLI, adds new template files, refreshes unchanged generated
+files, updates the package dependency and runs `npm install` to synchronize the
+lockfile and installed dependencies. Edited files are preserved and listed in the
+output. Review their new versions under `node_modules/orionplace-nuxt/templates`
+or `runtime` and merge your changes manually when needed. Removed upstream files
+are retained locally; the updater does not delete customer source.
+
+Domain mappings, domain settings and `.env` remain unchanged. The command does
+not deploy your application: restart development, or rebuild and redeploy the
+production frontend after updating.
+
+```bash
+npx orionplace-nuxt update --dry-run
+npm run orionplace:update
+```
+
+Dry-run downloads the latest CLI into npm's cache to inspect its templates but
+leaves project files and dependencies unchanged. `update --local` applies the
+version of the CLI being executed instead of fetching the latest CLI; it still
+installs project dependencies. Use this only when intentionally selecting a version.
+
+For a project on 0.1.2 or older, bootstrap the new command once:
+
+```bash
+npx --yes orionplace-nuxt@latest update
+```
+
+Updates require the existing `orionplace/settings.json` and `.generated.json`.
+Conflicting untracked files stop the source update before any writes. If dependency
+installation fails after source generation, run `npm install` and retry `update`.

package/bin/orionplace-nuxt.mjs

@@ -1,27 +1,36 @@
 #!/usr/bin/env node
 import { setupProject } from '../src/setup.mjs';
+import { updateProject } from '../src/update.mjs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 
 const help = `Orionplace Nuxt setup
 
+  npx orionplace-nuxt help
   npx orionplace-nuxt init [directory]
+  npx orionplace-nuxt update
   npx orionplace-nuxt set backend <personal-backend.orionplace.app>
   npx orionplace-nuxt add frontend <shop.example.com>
   npx orionplace-nuxt remove frontend <shop.example.com>
+  npx orionplace-nuxt set mimic <existing-frontend.example.com>
   npx orionplace-nuxt set frontend <shop.example.com>
 
 Options: --cwd <directory>  --dry-run  --help  --version
+Update option: --local (apply this CLI version instead of fetching the latest release)
 
+Update downloads the latest release, refreshes unedited source, and installs dependencies.
+It preserves edited source, domain mappings and MIMIC. --dry-run leaves project files unchanged.
 Set backend or add frontend also initializes the integration; either can come first.
-Add frontend keeps other domains and the current MIMIC domain. Set frontend selects MIMIC.
+MIMIC starts empty. The first added frontend sets it; later additions preserve it.
+Set mimic selects an existing frontend without changing any domain mappings.
+Set frontend is the legacy shortcut to add and select a frontend.
 Set backend updates every managed frontend mapping. Remove frontend deletes only that mapping.
 After creating a new project, run npm install and npm run dev in that directory.
 Documentation and editable server source are generated in orionplace/.`;
 try {
   const argv = process.argv.slice(2);
-  if (!argv.length || argv.includes('--help') || argv.includes('-h')) {
+  if (!argv.length || argv[0] === 'help' || argv.includes('--help') || argv.includes('-h')) {
     console.log(help);
   } else if (argv.includes('--version')) {
     console.log(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version);
@@ -29,8 +38,10 @@ try {
     const positional = [];
     let cwd = process.cwd();
     let dryRun = false;
+    let local = false;
     for (let index = 0; index < argv.length; index++) {
       if (argv[index] === '--dry-run') dryRun = true;
+      else if (argv[index] === '--local') local = true;
       else if (argv[index] === '--cwd') {
         if (!argv[index + 1]) throw new Error('--cwd needs a directory');
         cwd = resolve(argv[++index]);
@@ -38,29 +49,37 @@ try {
       else positional.push(argv[index]);
     }
     const [command, target] = positional;
+    if (local && command !== 'update') throw new Error('--local is only supported by update.');
     let result;
     if (command === 'init' && positional.length <= 2) {
       result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
-    } else if (((command === 'set' && ['backend', 'frontend'].includes(target)) ||
+    } else if (command === 'update' && positional.length === 1) {
+      result = await updateProject({ cwd, dryRun, local });
+    } else if (((command === 'set' && ['backend', 'frontend', 'mimic'].includes(target)) ||
         (['add', 'remove'].includes(command) && target === 'frontend')) && positional.length <= 3) {
       let value = positional[2];
       if (!value && process.stdin.isTTY) {
         const prompt = createInterface({ input: process.stdin, output: process.stdout });
-        try { value = await prompt.question(`${target === 'backend' ? 'Personal backend API' : 'Public frontend domain'}: `); }
+        try { value = await prompt.question(`${target === 'backend' ? 'Personal backend API' : target === 'mimic' ? 'Existing frontend to use for MIMIC' : 'Public frontend domain'}: `); }
         finally { prompt.close(); }
       }
       if (!value) throw new Error(`Provide the ${target} domain. See --help.`);
       result = await setupProject({ cwd, action: command, field: target, value, dryRun });
     } else throw new Error('Unknown command. See --help.');
-    console.log(`${dryRun ? 'Planned' : 'Updated'} ${result.root}`);
-    for (const path of result.changed) console.log(`  ${result.removed.includes(path) ? 'Remove: ' : ''}${path}`);
-    for (const path of result.preserved) console.log(`  Preserved your edits: ${path}`);
-    console.log(result.settings.backend && result.settings.frontend
-      ? `Ready: ${result.settings.frontends.join(', ')} -> ${result.settings.backend}\nLocal MIMIC: ${result.settings.frontend}`
-      : `Next: ${result.settings.backend ? 'add frontend' : 'set backend'} to complete the domain mapping.`);
-    if (result.changed.some(path => path.endsWith('.cfg') || path === '.env')) console.log('Restart a running development server to refresh allowed hosts and MIMIC. Reload your production environment when changing MIMIC.');
-    if (result.isNewNuxt) console.log('Run npm install in the project, then npm run dev.');
-    console.log('Project documentation: orionplace/README.md');
+    if (result) {
+      console.log(`${dryRun ? 'Planned' : 'Updated'} ${result.root}`);
+      for (const path of result.changed) console.log(`  ${result.removed.includes(path) ? 'Remove: ' : ''}${path}`);
+      for (const path of result.preserved) console.log(`  Preserved your edits: ${path}`);
+      console.log(result.settings.backend && result.settings.frontend
+        ? `Ready: ${result.settings.frontends.join(', ')} -> ${result.settings.backend}\nLocal MIMIC: ${result.settings.frontend}`
+        : `Next: ${result.settings.backend ? 'add frontend' : 'set backend'} to complete the domain mapping.`);
+      if (result.changed.some(path => path.endsWith('.cfg') || path === '.env')) console.log('Restart a running development server to refresh allowed hosts and MIMIC. Reload your production environment when changing MIMIC.');
+      if (result.isNewNuxt) console.log('Run npm install in the project, then npm run dev.');
+      console.log('Project documentation: orionplace/README.md');
+      if (command === 'update') console.log(dryRun
+        ? 'Dependency installation would run after applying these changes. Project files were not changed.'
+        : 'Update complete. Restart development, or rebuild and redeploy your production frontend.');
+    }
   }
 } catch (error) {
   console.error(`Orionplace: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-nuxt",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Nuxt integration and setup CLI for your Orionplace personal marketplace backend.",
   "type": "module",
   "license": "MIT",
@@ -31,11 +31,12 @@
     "bin",
     "src",
     "runtime",
+    "templates",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --experimental-strip-types --test test/*.test.mjs"
   },
   "peerDependencies": {
     "nuxt": "^4.0.0"

package/src/module.mjs

@@ -29,6 +29,8 @@ export default defineNuxtModule({
     // Do not inherit page caching for authenticated API requests.
     routes['/api/**'] = { ...routes['/api/**'], cache: false, swr: false,
       headers: { ...routes['/api/**']?.headers, 'cache-control': 'no-store' } };
+    // MIMIC defaults to empty. The CLI sets .env on the first "add frontend"
+    // or an explicit "set mimic"; never infer it from the domain-file directory.
     // Values stay private to the server. MIMIC_FRONT_DOMAIN is also read at runtime.
     nuxt.options.runtimeConfig.mimicFrontDomain ??= '';
     nuxt.options.runtimeConfig.mimicFrontDomain = process.env.MIMIC_FRONT_DOMAIN

package/src/project-readme.mjs

@@ -10,7 +10,7 @@ You can change that backend domain in your account, then update this project.
 ## Current setup
 
 - Frontend domains: ${settings.frontends?.length ? settings.frontends.map(domain => '\`' + domain + '\`').join(', ') : 'not configured yet'}
-- Local MIMIC domain: \`${settings.frontend || '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:
@@ -26,9 +26,19 @@ Set the backend or add a frontend first; either order works. Each frontend has i
 own \`sitemaps/<domain>.cfg\` mapping to your personal API. Adding a domain again
 is safe. Changing the backend updates every CLI-managed frontend mapping.
 
-The first added frontend becomes \`MIMIC_FRONT_DOMAIN\` in \`.env\`. Adding more
-domains preserves that choice. Use \`npx orionplace-nuxt set frontend <domain>\`
-to add and select a different local domain.
+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-nuxt 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-nuxt help
+npx orionplace-nuxt 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
@@ -88,53 +98,88 @@ In another terminal:
 \`\`\`bash
 curl -i http://localhost:3000/api/appload \\
   -H 'Content-Type: application/json' \\
-  --data '{"ignore_cache":true,"detalize_mode":"full"}'
+  --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.
 
-Browser requests use the storefront's own API path:
-
-\`\`\`javascript
-const response = await fetch('/api/appload', {
-  method: 'POST',
-  credentials: 'same-origin',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ ignore_cache: true, detalize_mode: 'full' }),
-});
-const result = await response.json();
-console.log(response.status, result);
-\`\`\`
+## AppLoad initialization
+
+The generated \`app/app.vue\` calls \`useOrionplaceAppLoad()\` and displays loading,
+success or failure, HTTP status, session state and counts of returned sections.
+Use **Reload AppLoad** to issue a fresh request. A failed request never opens a
+login modal. Once the connection works, replace this debug page with your storefront.
+
+| Project file | Purpose |
+| --- | --- |
+| \`app/composables/useOrionplaceAppLoad.ts\` | SSR-aware initialization and manual reload. |
+| \`app/utils/orionplaceAppLoad.ts\` | HTTP, form-error and bootstrap-envelope checks. |
+| \`app/interfaces/orionplace/index.ts\` | All AppLoad interfaces and nested model exports. |
+| \`app/interfaces/orionplace/transport.ts\` | Request, response, result and error contracts. |
+
+The interfaces cover initialization settings, locales, currencies, units, catalog,
+products, banners, events, tariffs and subscriptions, API discovery and forms,
+and the optional signed-in profile. Plugin-defined JSON remains explicitly typed
+as JSON; interfaces are not a full runtime schema validator.
 
-For SSR, use Nuxt's \`useRequestFetch()\` so the request's domain, cookie and
-authorization headers reach the same gateway. For example, in \`app/app.vue\`:
+The server uses the current request's domain and session. Its result is reused
+during browser hydration, and new response cookies are relayed to the browser.
+The page response uses \`private, no-store\`; do not put personalized pages behind
+shared HTML caches. Reloading replaces the current session's discovery data.
+
+Requests use \`detalize_mode: "light"\` and \`ignore_cache: true\`. Tenant settings
+can override these options, and individual initialization sections have separate
+backend caches. Full endpoint descriptions are therefore optional.
+
+If your project already has a custom \`app/app.vue\`, the CLI preserves it.
+Integrate the generated composable explicitly:
 
 \`\`\`vue
-<script setup>
-const requestFetch = useRequestFetch();
-const { data, error } = await useAsyncData('marketplace-initialization', () =>
-  requestFetch('/api/appload', {
-    method: 'POST',
-    body: { ignore_cache: true, detalize_mode: 'full' },
-  }),
-);
+<script setup lang="ts">
+import { useOrionplaceAppLoad } from './composables/useOrionplaceAppLoad';
+const { data, status, error, refresh } = await useOrionplaceAppLoad();
+// data.value?.response.page_data contains the typed initialization and discovery.
 </script>
 
 <template>
   <main>
-    <p v-if="error">The marketplace API is currently unavailable.</p>
-    <pre v-else>{{ data }}</pre>
+    <p role="status">AppLoad: {{ status }}</p>
+    <p v-if="error" role="alert">Marketplace initialization failed.</p>
+    <button type="button" :disabled="status === 'pending'" @click="refresh()">Reload AppLoad</button>
+    <p v-if="data">HTTP {{ data.httpStatus }}</p>
   </main>
 </template>
 \`\`\`
 
-Keep private data out of shared caches. This SSR example forwards incoming cookies;
-it does not relay new upstream cookies to the browser. Make session-changing calls
-from the browser, or explicitly append each returned Set-Cookie header to the SSR
-response in your server integration.
+Call the composable once in your app root and pass the data to your components.
+The generated debug view displays section summaries; it does not render profile
+fields, keys or backend exception stacks. The typed response is still available
+to your application, so avoid logging or publishing it indiscriminately.
+
+CLI reruns preserve edited generated source. Review updated package templates
+manually when you have customized a file. Existing custom apps are not replaced.
+
+## Update the package and components
+
+Run this from your project root whenever you want the latest release:
+
+\`\`\`bash
+npx orionplace-nuxt 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-nuxt/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-nuxt 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
 

package/src/setup.mjs

@@ -57,17 +57,21 @@ function updateEnvironment(source, domain) {
 }
 
 export async function setupProject({ cwd = process.cwd(), action = 'set', field, value, dryRun = false } = {}) {
-  if (!['set', 'add', 'remove'].includes(action) || (action !== 'set' && field !== 'frontend')) {
-    throw new Error('Use set backend, add frontend, remove frontend, or set frontend.');
+  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) : field === 'frontend' ? frontendDomain(value) : null;
-  if (field && !setting) throw new Error('Choose backend or frontend.');
+  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', 'nuxt.config.ts', 'nuxt.config.js', 'nuxt.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, type: 'module' };
   const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  if (action === 'update' && (!dependencies.nuxt || !current['orionplace/settings.json'] || !current['orionplace/.generated.json'])) {
+    throw new Error('Update requires an initialized Orionplace Nuxt project. Run init first.');
+  }
   if (!dependencies.nuxt && ['next', '@sveltejs/kit'].some(name => dependencies[name])) throw new Error('This package sets up Nuxt projects only.');
   if (dependencies.nuxt && !/^(?:[~^]|>=)?4(?:\.|$)/.test(dependencies.nuxt)) {
     throw new Error('This release supports Nuxt 4. Upgrade your Nuxt dependency before setup.');
@@ -98,6 +102,12 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   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}`);
@@ -143,24 +153,56 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   pkg.scripts['orionplace:frontend'] ||= 'orionplace-nuxt set frontend';
   pkg.scripts['orionplace:add-frontend'] ||= 'orionplace-nuxt add frontend';
   pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-nuxt remove frontend';
+  pkg.scripts['orionplace:mimic'] ||= 'orionplace-nuxt set mimic';
+  pkg.scripts['orionplace:help'] ||= 'orionplace-nuxt help';
+  pkg.scripts['orionplace:update'] ||= 'orionplace-nuxt update';
   pkg.dependencies ||= {};
   pkg.dependencies['orionplace-nuxt'] ||= dependencies['orionplace-nuxt'] || `^${metadata.version}`;
+  if (action === 'update') {
+    pkg.dependencies['orionplace-nuxt'] = metadata.version;
+    if (pkg.devDependencies) delete pkg.devDependencies['orionplace-nuxt'];
+  }
   if (isNewNuxt) {
     pkg.dependencies.nuxt = '^4.5.0';
     pkg.dependencies.vue ||= '^3.5.0';
     pkg.dependencies['vue-router'] ||= '^5.0.0';
   }
+  // Install the complete editable AppLoad source. Never replace a customer's app.
+  const appPath = 'app/app.vue';
+  const existingApp = await read(await safePath(root, appPath));
+  const installApp = existingApp === null || Boolean(previous[appPath]);
+  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 (name === appPath && !installApp) continue;
+      await plan(name, await readFile(new URL(name, templateRoot), 'utf8'), { managed: true, preserve: true });
+    }
+  }
+  await planTemplates();
+  if (installApp && !dependencies.sass && !dependencies['sass-embedded']) {
+    pkg.devDependencies ||= {};
+    pkg.devDependencies.sass = '^1.102.0';
+  }
+  if (!await read(await safePath(root, 'tsconfig.json'))) {
+    await plan('tsconfig.json', JSON.stringify({ files: [], references: [
+      { path: './.nuxt/tsconfig.app.json' }, { path: './.nuxt/tsconfig.server.json' },
+      { path: './.nuxt/tsconfig.shared.json' }, { path: './.nuxt/tsconfig.node.json' },
+    ] }, null, 2) + '\n', { managed: true });
+  }
   await plan('package.json', JSON.stringify(pkg, null, 2) + '\n');
   for (const file of ['marketplace.mjs', 'api.mjs', 'domain.mjs']) {
     await plan(`orionplace/runtime/${file}`, await readFile(new URL(`../runtime/${file}`, import.meta.url), 'utf8'), { managed: true, preserve: true });
   }
   await plan('orionplace/README.md', projectReadme(settings), { managed: true, preserve: true });
-  if (isNewNuxt && !(await read(await safePath(root, 'app/app.vue')))) {
-    await plan('app/app.vue', '<template>\n  <main>\n    <h1>Your marketplace</h1>\n    <p>Domain setup and API instructions are in orionplace/README.md.</p>\n  </main>\n</template>\n', { managed: 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.frontend || oldFrontend) await plan('.env', updateEnvironment(current['.env'], settings.frontend || ''));
-  if (settings.backend) {
-    const mappings = action === 'remove' ? []
+  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 });
@@ -172,7 +214,7 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
     if (!ignore.split(/\r?\n/).includes(entry)) ignore = ignore.replace(/\n*$/, '\n') + entry + '\n';
   }
   await plan('.gitignore', ignore);
-  await plan('orionplace/settings.json', JSON.stringify(settings, null, 2) + '\n');
+  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) {

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 Nuxt release…');
+    await npm(['exec', '--yes', '--prefer-online', '--package=orionplace-nuxt@latest', '--',
+      'orionplace-nuxt', '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/templates/app/app.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useHead } from '#imports';
+import { useOrionplaceAppLoad } from './composables/useOrionplaceAppLoad';
+import type { IAppLoadPathsRecord } from './interfaces/orionplace';
+
+useHead({ title: 'Marketplace · AppLoad debug' });
+const { data, status, error, refresh } = await useOrionplaceAppLoad();
+const page = computed(() => data.value?.response.page_data);
+const init = computed(() => page.value?.init);
+const countEndpoints = (routes?: IAppLoadPathsRecord) =>
+  Object.values(routes?.paths ?? {}).reduce((total, section) => total + Object.keys(section).length, 0);
+const stateLabel = computed(() => ({ idle: 'Not started', pending: 'Loading', success: 'Loaded', error: 'Failed' })[status.value]);
+const failure = computed(() => error.value?.data);
+</script>
+
+<template>
+  <main class="bootstrap">
+    <header>
+      <p class="eyebrow">Orionplace · Nuxt starter</p>
+      <h1>Your marketplace connection</h1>
+      <p>This first page checks initialization through <code>POST /api/appload</code>.
+        Replace it with your storefront when the connection is ready.</p>
+    </header>
+    <section aria-labelledby="status-title" :aria-busy="status === 'pending'">
+      <div class="section-heading">
+        <h2 id="status-title">AppLoad state</h2>
+        <button type="button" :disabled="status === 'pending'" @click="refresh()">Reload AppLoad</button>
+      </div>
+      <p role="status" aria-live="polite" class="state" :data-state="status">{{ stateLabel }}</p>
+      <p v-if="status === 'pending'">Loading initialization data and available API endpoints…</p>
+      <div v-else-if="error" role="alert">
+        <p>AppLoad could not initialize. {{ failure?.kind === 'validation' ? 'The backend returned form errors.' :
+          failure?.kind === 'invalid-response' ? 'The response is missing required initialization data.' :
+          failure?.kind === 'network' ? 'The API request did not complete.' : 'The API returned an HTTP error.' }}</p>
+        <p v-if="failure?.httpStatus">HTTP status: <code>{{ failure.httpStatus }}</code></p>
+        <p>Check your backend, frontend domain and <code>MIMIC_FRONT_DOMAIN</code> using
+          <code>npx orionplace-nuxt help</code>. Setup instructions are in <code>orionplace/README.md</code>.</p>
+      </div>
+      <dl v-else-if="data && init">
+        <div><dt>HTTP status</dt><dd>{{ data.httpStatus }}</dd></div>
+        <div><dt>Loaded at (UTC)</dt><dd><time :datetime="data.loadedAt">{{ data.loadedAt }}</time></dd></div>
+        <div><dt>Session</dt><dd>{{ init.is_authenticated ? 'Signed in' : 'Guest' }}</dd></div>
+        <div><dt>Languages</dt><dd>{{ Object.keys(init.locale).length }}</dd></div>
+        <div><dt>Currencies</dt><dd>{{ Object.keys(init.currencies).length }}</dd></div>
+        <div><dt>Public endpoints</dt><dd>{{ countEndpoints(page?.unauth) }}</dd></div>
+        <div><dt>Authenticated endpoints</dt><dd>{{ countEndpoints(page?.auth) }}</dd></div>
+        <div><dt>Catalog roots</dt><dd>{{ init.catalog?.length ?? 'Not included' }}</dd></div>
+        <div><dt>Initial products</dt><dd>{{ init.products?.length ?? 'Not included' }}</dd></div>
+        <div><dt>Tariffs</dt><dd>{{ init.tariffs?.data.length ?? 'Not included' }}</dd></div>
+      </dl>
+    </section>
+    <section aria-labelledby="next-title">
+      <h2 id="next-title">Build from typed initialization data</h2>
+      <p>The request lives in <code>app/composables/useOrionplaceAppLoad.ts</code>.
+        The response and its nested interfaces are in <code>app/interfaces/orionplace/</code>.</p>
+      <p>This debug page shows section counts. Account details, keys and backend diagnostics are not displayed.</p>
+      <a href="https://orionmarket.place/sandbox">Read the marketplace documentation</a>
+    </section>
+  </main>
+</template>
+
+<style lang="scss">
+body { margin: 0; background: #f5f6f8; color: #202b38; font-family: system-ui, sans-serif; }
+.bootstrap {
+  max-width: 860px; margin: 0 auto; padding: 48px 24px;
+  h1, h2 { font-weight: 400; line-height: 1.25; }
+  h1 { font-size: 32px; margin: 12px 0; }
+  h2 { font-size: 21px; margin: 0; }
+  p { line-height: 1.7; }
+  .eyebrow { color: #596777; font-size: 14px; }
+  section { margin-top: 28px; padding: 24px; border: 1px solid #d9dfe6; border-radius: 10px; background: #fff; }
+  .section-heading { display: flex; align-items: center; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+  .state { display: inline-block; padding: 4px 12px; border-radius: 4px; background: #eaf0f5;
+    &[data-state='success'] { background: #e6f2ec; color: #245c40; }
+    &[data-state='error'] { background: #fbeceb; color: #8c302a; }
+  }
+  button { font: inherit; color: inherit; background: #f5f6f8; border: 1px solid #bfc9d4; border-radius: 5px; padding: 9px 14px; cursor: pointer;
+    &:disabled { opacity: .6; cursor: wait; }
+    &:hover:not(:disabled) { background: #eaf0f5; }
+  }
+  a { color: #245786; text-underline-offset: 3px; }
+  :focus-visible { outline: 2px solid #245786; outline-offset: 4px; }
+  code { font-size: .9em; overflow-wrap: anywhere; }
+  dl { margin-bottom: 0; div { display: grid; grid-template-columns: minmax(140px, 1fr) 2fr; gap: 12px; padding: 12px 0; border-top: 1px solid #e8ecf0; }
+    dt { color: #596777; } dd { margin: 0; overflow-wrap: anywhere; }
+  }
+  @media (max-width: 520px) { padding: 24px 16px; section { padding: 18px; } dl div { grid-template-columns: 1fr; gap: 4px; } }
+}
+</style>