orionplace-nuxt 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,28 @@
 # orionplace-nuxt
 
-Set up a Nuxt 4 storefront for your personal Orionplace marketplace API.
-The package includes a Nuxt module, a setup CLI, and commented server source
-that is copied into your project alongside an integration README.
+**A complete Nuxt 4 storefront for your Orionplace marketplace, set up with one command.**
+
+`orionplace-nuxt` creates a server-rendered shop connected to your personal
+marketplace API: catalog and search, product pages, cart and checkout, customer
+account, journal and support, in English and Russian. The package includes a Nuxt module, a
+setup CLI and the full storefront source, so every page and component in your
+project is yours to change.
+
+- **Setup CLI:** `init`, `set backend`, `add frontend`, `set mimic` and `update`.
+- **Server install:** `install` builds the storefront on your Linux server and
+  runs it as a system service behind nginx with HTTPS.
+- **API gateway:** the browser calls `/api/...` on your own domain; the server
+  forwards it to your marketplace backend with cookies bound to the storefront.
+- **Typed store:** one Application Load request fills it before the first render.
+- **124 storefront components**, each with an English and Russian README
+  ([list](#components)).
+- **Several storefront domains** on one backend, each with its own mapping.
+- **Android app** from the same project with Capacitor 8.
+
+**Contents:** [Quick start](#quick-start-from-zero) ·
+[Existing project](#existing-nuxt-4-project) · [Components](#components) ·
+[Commands](#commands) · [Server install](#install-on-your-server) ·
+[Android app](#android-app) · [Update](#update-an-existing-project)
 
 Requires Node.js 22.12+ and a Node server deployment. Static-only and edge
 hosting are not supported by this filesystem-based integration.
@@ -106,6 +126,188 @@ Use `@/` for application imports. Nuxt resolves it to `app/`, so an import such
 as `@/stores/orionplace` works from any page, composable or component folder.
 Framework imports such as `#imports` keep their own names.
 
+<!-- components:start (generated by scripts/generate-package-readme-components.mjs) -->
+## Components
+
+The starter includes **124 storefront components**, copied into
+`app/components/orionplace/` of your project. Each one has a README in English and Russian
+next to its source that describes its inputs, data and actions.
+
+### Storefront structure
+
+Main pages and the shared storefront frame.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Header** | `StorefrontHeader` | The storefront header and its search, catalog, manufacturer and journal links, locale, currency, account, wishlist and cart controls. |
+| **Storefront logo** | `BrandLogos` | Displays one logo from store.init.logos. |
+| **Product search** | `MainSearch` | A search input with suggestions in the storefront language. |
+| **Language selector** | `MainLanguageSwitcher` | Selects the storefront language and its associated currency and measurement units. |
+| **Currency selector** | `MainCurrencySwitcher` | Selects the current storefront currency from the available options. |
+| **Storefront account** | `StorefrontAccount` | Guest sign-in button and signed-in account menu with profile and wallet actions. |
+| **Wallet balance** | `WalletBalance` | Displays the wallet balance in the selected storefront currency. |
+| **Sign-out page** | `StorefrontLogout` | Session sign-out, failure retry and return to the storefront. |
+| **Wishlist button** | `StorefrontWishlistButton` | Displays the wishlist count and links to the wishlist page. |
+| **Cart button** | `StorefrontCartButton` | Displays the cart count and emits a request to open the cart page. |
+| **Cart preview** | `CartPreview` | A compact dropdown under the header's cart button with cart products, quantities and amounts in the selected currency. |
+| **Catalog menu** | `CatalogHeader` | Category navigation with nested sections and representative product cards. |
+| **Catalog representative** | `CatalogRepresentative` | A compact product card used in the catalog menu, with the same navigation, variant, wishlist and purchase actions. |
+| **Storefront home** | `StorefrontHome` | Banners, the optional Popular categories block, product sections, storefront events and recommendations. |
+| **Storefront banners** | `MainBanner` | A carousel of banner images for the current storefront language, with responsive image formats. |
+| **Popular categories block** | `CategoryGroup` | Optional home-page block of public category tiles. |
+| **Product group** | `ProductGroup` | Displays a collection of product cards with images, prices, variant selection and purchase controls. |
+| **Product card** | `ProductCard` | Combines a product’s image, name, price, variants, wishlist button and purchase controls in one card. |
+| **Product photo viewer** | `HoverImageViewer` | A separate product photo viewer with dot buttons: it switches photos with the pointer, with a swipe and from the keyboard, and a click passes the chosen photo's address to the application. |
+| **Product card title** | `ProductCardTitle` | Displays the localized product name in the card. |
+| **Product card description** | `ProductCardDescription` | Displays the localized short product description as plain text, with HTML tags removed. |
+| **Product card badges** | `ProductCardBadges` | Marks new, popular, good-deal and low-stock products with badges in the card. |
+| **Product card wishlist button** | `ProductCardFavorite` | Requests adding or removing the product from the wishlist; the supplied storefront sends guests to sign-in. |
+| **Seller in the product card** | `ProductCardSeller` | Displays the product seller’s name and rating in the card. |
+| **Product card rating** | `ProductCardRating` | Displays the product’s average rating and review count in the card. |
+| **Product card variants** | `ProductCardVariants` | Selects a primary or secondary product variant. |
+| **Secondary variant selector** | `ProductSecondaryVariantModal` | Shows primary and secondary product choices in a modal and can continue the selected purchase action. |
+| **Product card price** | `ProductCardPrice` | Displays the price in the selected currency and the original price when the product is discounted. |
+| **Low-stock notice** | `ProductCardStockNotice` | Warns that the product will soon run out of stock. |
+| **Product card purchase controls** | `ProductCardActions` | Product-card controls for the cart, quantity, availability notifications and preorder when available. |
+| **Preorder dialog** | `ProductPreorderDialog` | The selected product and contact details for a preorder request. |
+| **Storefront events** | `EventsBlock` | A full-width carousel of layout-event images for the current storefront language, with responsive image formats. |
+| **Event block and promotion enrollment** | `EventEnrollmentDialog` | Displaying the event block and opening promotion enrollment from the selected event. |
+| **Footer** | `StorefrontFooter` | Store identity, navigation, a contact-page link and social links. |
+| **Social links** | `SocialLinks` | Display the store’s published social links and icons. |
+| **Error page** | `StorefrontErrorPage` | Page-not-found (404) and failure (500) page with Home, Catalog and Retry actions. |
+| **Storefront theme** | `OrionplaceThemeProvider` | Applies the selected light or dark storefront theme and optional color overrides to its content. |
+
+### Catalog and discovery
+
+Browse categories, search results and product sources.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Catalog component** | `StorefrontCatalog` | The component shows store categories, subcategories and product links. |
+| **Category page** | `StorefrontCategory` | A category with its breadcrumb path, subcategories, filters and paginated product cards. |
+| **Search results** | `ProductSearchResults` | Filters, products, loading and empty states for search, category, seller and recommendation results. |
+| **Search filters** | `SearchFilters` | Price, discount, rating, review, category, seller, manufacturer and variant facets with selectable values and optional result counts. |
+| **Sellers** | `StorefrontSellers` | Seller directory with filters and sorting, and a seller profile with its products. |
+| **Seller filters** | `SellerFilters` | Seller name, minimum rating and category filters for the seller directory. |
+| **Seller summary** | `SellerSummary` | Seller logo, name, rating, selling-since badge, product count and description. |
+| **Seller photos** | `SellerPhotoGallery` | The seller’s approved photos as a square grid with a photo viewer. |
+| **Stores** | `StorefrontStores` | Store addresses, map, phone numbers, opening hours and products. |
+| **Manufacturers and their products** | `StorefrontManufacturers` | Alphabetical index, letter-based lists and manufacturer details. |
+| **Manufacturer index** | `ManufacturerIndex` | Manufacturer logos and letter groups. |
+
+### Products and shopping
+
+Product details, saved items and the cart.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Product details** | `StorefrontProduct` | Loads and displays a published product or a secret-key preview with images, purchase choices, details and reviews. |
+| **Page path** | `OrionplaceBreadcrumbs` | Linked path from the storefront home page through parent categories to the current page. |
+| **Product characteristics** | `ProductSpecificationsDialog` | Every characteristic of the product in a dialog over the page. |
+| **Product reviews** | `ProductReviews` | Reviews, replies, ratings and the user’s submissions. |
+| **Review form** | `ProductReviewForm` | Rating, text and photos for a review or reply. |
+| **Customer review photos** | `ProductReviewGallery` | Review photos for the selected product. |
+| **Review photo viewer** | `ProductReviewImageViewer` | The photos of one review, shown large on the same page. |
+| **Promo code products** | `PromoProducts` | The products a promo code offer applies to, with the offer’s conditions. |
+| **Wishlist and availability notices** | `StorefrontWishlist` | Saved products and products with availability notifications, shown as standard product cards. |
+| **Cart and checkout** | `StorefrontCart` | Cart items, promo codes, delivery, payment and order creation. |
+| **Cart item** | `CartLineItem` | Item name, image, price, quantity and removal. |
+| **Cart item options** | `CartItemOptions` | Option products as product cards, with text and file attachment for an item. |
+| **Checkout details** | `CartCheckoutDetails` | Delivery address, payment method, recipient and comment. |
+| **Shipment delivery selection** | `CartDeliverySelector` | Delivery methods with icons, pickup points and their map for one shipment. |
+| **Delivery map** | `DeliveryMap` | Selectable locations on Yandex Maps for delivery pickup and the store directory. |
+
+### Customer account
+
+Profile, orders, addresses and account activity.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Account sections** | `AccountSection` | Account navigation and sign-in for private storefront sections. |
+| **Personal profile** | `StorefrontProfile` | Account overview and forms for personal details, verified email, notification preferences, avatar, password and account deletion. |
+| **Profile photo** | `ProfileAvatar` | Upload or remove the current account’s avatar. |
+| **Personal details** | `ProfileDetailsForm` | Edit the account holder’s name and date of birth. |
+| **Email and notifications** | `ProfileEmailSettings` | Verify an email address and choose optional email-notification and email-language preferences. |
+| **Account password** | `ProfilePasswordForm` | Create or change the account password. |
+| **Password field** | `OrionplacePasswordInput` | Password input with a button that shows or hides the entered password. |
+| **Delete account** | `ProfileDeleteAccount` | Delete the signed-in customer's own account. |
+| **Account sign-in** | `ProfileSignIn` | Phone-based account sign-in and registration. |
+| **User promo codes** | `AccountPromocodes` | Available promo codes and applying a selected code to the cart. |
+| **My activity** | `AccountActivity` | The user’s promo codes, reviews and sign-in history. |
+| **Sign-in history** | `SignInHistory` | The user’s sign-in dates, devices, browsers and IP addresses. |
+| **User orders** | `StorefrontOrders` | Order history, purchased items, payment, cancellation and repeat. |
+| **Order details** | `OrderDetails` | Order items, shipments, tracking, purchased content and attachments. |
+| **Order payment selection** | `OrderPaymentForm` | Available payment-method selection for an existing order. |
+| **User addresses** | `StorefrontAddresses` | Saved addresses, address editing and default delivery selection. |
+| **Address form** | `AddressForm` | Address creation and editing with country selection, region search, text suggestions and location lookup. |
+| **Value selector** | `OrionplaceSelect` | Selects one value from a labeled list, with keyboard controls, country flags and option icons. |
+| **Search selector** | `OrionplaceSearchSelect` | Selects one value from options searched as the user types, with a loading spinner and retry. |
+| **Wallet and payments** | `StorefrontWallet` | Payment history, balance top-ups and cancellation of unpaid invoices. |
+| **Wallet top-up form** | `WalletTopUpForm` | Amount, currency and payment-method selection for a wallet top-up. |
+| **Payment panel** | `PaymentPanel` | Opens the payment link and lets the user refresh its status. |
+| **Pagination** | `StorefrontPagination` | Previous and next controls with the current page for a returned list. |
+
+### Subscriptions and support
+
+Plans, active subscriptions and support requests.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Subscription plans** | `StorefrontTariffs` | Plans grouped by subscription, with search, sign-in for guests and subscription purchase. |
+| **Subscription plan details** | `StorefrontTariff` | One public plan with its media, description, features, periods, options and subscription purchase. |
+| **Subscription plans** | `TariffCards` | Plan cards in a responsive grid. |
+| **Subscription plan card** | `TariffCard` | A plan card with its image, trial badge, name, description, the modules and limits of the plan, the option chooser, period prices and subscribe actions. |
+| **Plan image** | `TariffCardImage` | The first small plan image. |
+| **Plan name** | `TariffCardTitle` | The tariff name in its card, in the selected language. |
+| **Plan description** | `TariffCardDescription` | The short plan description without HTML tags, and the full description under Details. |
+| **Plan modules, limits and options** | `TariffCardFeatures` | The modules and limits of a plan from `tariff_variables_json`, each with its explanation, and the chooser of the plan options. |
+| **Information hint** | `OrionplaceInfoHint` | Small information button that explains the term beside it. |
+| **Plan prices** | `TariffCardPrices` | The period switcher, the price for the chosen period and the Subscribe and Try actions. |
+| **Plan purchase** | `TariffSubscriptionModal` | Select an option, enter a promotion code and confirm a subscription purchase. |
+| **My subscriptions** | `StorefrontSubscriptions` | Subscription dates, plan, usage, service details, automatic renewal, renewal payment and support. |
+| **Renewal payment** | `SubscriptionExtendDialog` | The period, the promo code and the amount for extending a subscription. |
+| **Automatic renewal** | `SubscriptionRenewalDialog` | The period that is paid automatically, or turning it off. |
+| **Plan and option change** | `SubscriptionChangeDialog` | The new plan or service option, its period and the amount that is charged. |
+| **Subscription cancellation** | `SubscriptionCancelDialog` | The confirmation that stops automatic renewal and keeps the paid period. |
+| **Plan and usage** | `SubscriptionPlanSummary` | The plan picture, description and parameters with the usage the subscription service reported. |
+| **Subscription service details** | `SubscriptionRemoteDetails` | The identifier, confirmation time and host a subscription service returned. |
+| **Support conversations** | `StorefrontSupport` | Customer support conversations for general questions, sellers, order items and subscriptions. |
+| **Conversation messages** | `TicketConversation` | Messages, attachments, conversation closing and support rating. |
+| **Conversation item** | `TicketItemCard` | The purchased item a conversation is about, with its image, variant or option, quantity and paid amount. |
+| **Subscription of a conversation** | `TicketSubscriptionCard` | The subscription a support conversation is about: plan, number, state, paid-until date and automatic renewal. |
+| **Conversation image** | `TicketImage` | Loading and viewing an image from the user’s conversation. |
+| **Support message form** | `TicketMessageForm` | Message text and images for a new conversation or reply. |
+
+### Content and contact
+
+Journal content and customer contact flows.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Journal** | `StorefrontJournal` | Paged journal of store articles with category and author filters. |
+| **Journal article** | `BlogArticle` | An article, subscription access and its discussion. |
+| **Article comments** | `BlogComments` | Discussion, replies and the user’s own comments. |
+| **Comment form** | `BlogCommentForm` | Text for a new comment, reply or edit. |
+| **Blog posts** | `BlogPostGroup` | Publication previews in a grid, list or layout with a lead card. |
+| **Blog post card** | `BlogPostCard` | Publication image, localized title, plain-text preview and reading time. |
+| **Contact page** | `StorefrontContact` | Company contact and registration details, with a form for messaging the store. |
+| **Contact details** | `AboutPage` | Display the store’s published company and contact information. |
+| **Contact form** | `ContactForm` | Sending a question to the store. |
+| **Unsubscribe from emails** | `EmailUnsubscribe` | Confirming an unsubscribe request from an email link. |
+
+### Shared interface
+
+Small reusable states and identity elements.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Empty state** | `OrionplaceEmptyState` | Line drawing and message shown when a list, history or search result has no items. |
+| **Avatar** | `OrionplaceAvatar` | Round user photo with initials when no photo is available. |
+| **Storefront image** | `OrionplaceImage` | Loads a safe public image lazily and shows an accessible placeholder when the image is missing or fails. |
+| **Measurement unit selector** | `UnitSwitcher` | Selects a weight or length unit from those available in the storefront. |
+
+<!-- components:end -->
+
 ## Commands
 
 ```bash
@@ -116,6 +318,7 @@ 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 mimic shop.example.com
+sudo npx orionplace-nuxt install
 npx orionplace-nuxt help
 ```
 
@@ -132,8 +335,38 @@ npm run orionplace:update
 ```
 
 `npm set` belongs to npm's own configuration system; use the commands above.
-These commands configure local integration files. They do not provision a backend,
-change your account, create DNS records, configure TLS, or deploy a VPS.
+The setup commands configure local integration files. They do not provision a
+backend, change your account or create DNS records. `install` deploys the
+storefront on your server; see [Install on your server](#install-on-your-server).
+
+## Install on your server
+
+Prepare a Linux server once with the OrionMarketplace server script: it installs
+Node.js, nginx and certbot and adds the `orionplace` command
+([server guide](https://orionmarket.place/en/sandbox/install)).
+
+```bash
+curl -fsSLo orionplace.sh https://orionmarket.place/downloads/orionplace.sh
+sudo sh orionplace.sh setup
+```
+
+Then create the storefront in `/srv/orionplace` and install it:
+
+```bash
+cd /srv/orionplace
+sudo npx --yes orionplace-nuxt init shop
+cd shop
+sudo npm install
+sudo npx orionplace-nuxt install
+```
+
+`install` asks for your backend and storefront domain when they are missing,
+builds the project, runs it as the system service `orionplace-shop` on a free
+local port and connects each storefront domain with nginx and a Let's Encrypt
+certificate. Run it again after code or package updates; the service keeps its
+port. Options: `--name <service>`, `--port <port>`, `--user <user>`,
+`--no-domains`, `--yes`, `--dry-run`. Full guide:
+[Install a storefront](https://orionmarket.place/en/sandbox/install/storefront).
 
 ## Generated files
 

package/bin/orionplace-nuxt.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { setupProject } from '../src/setup.mjs';
 import { updateProject } from '../src/update.mjs';
+import { installService } from '../src/install.mjs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -29,8 +30,16 @@ Commands for an existing project (run from its root):
   npx orionplace-nuxt set mimic <existing-frontend.example.com>
   npx orionplace-nuxt set frontend <shop.example.com>
 
+On your Linux server (run from the project root):
+  sudo npx orionplace-nuxt install
+  Builds the storefront, installs it as a system service (systemd or OpenRC)
+  and, when the orionplace server tool is set up, connects its domains with
+  nginx and HTTPS. Run it again after changes or an update to rebuild and restart.
+  Server tool: https://orionmarket.place/downloads/orionplace.sh
+
 Options: --cwd <directory>  --dry-run  --help  --version
 Update option: --local (apply this CLI version instead of fetching the latest release)
+Install options: --name <service>  --port <port>  --user <user>  --no-domains  --yes
 
 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.
@@ -52,10 +61,16 @@ try {
     let cwd          = process.cwd();
     let dryRun       = false;
     let local        = false;
+    const install    = { domains: true, yes: 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') {
+      else if (argv[index] === '--no-domains') install.domains = false;
+      else if (argv[index] === '--yes' || argv[index] === '-y') install.yes = true;
+      else if (['--name', '--port', '--user'].includes(argv[index])) {
+        if (!argv[index + 1]) throw new Error(`${argv[index]} needs a value`);
+        install[argv[index].slice(2)] = argv[++index];
+      } else if (argv[index] === '--cwd') {
         if (!argv[index + 1]) throw new Error('--cwd needs a directory');
         cwd = resolve(argv[++index]);
       } else if (argv[index].startsWith('--')) throw new Error(`Unknown option: ${argv[index]}`);
@@ -63,8 +78,28 @@ try {
     }
     const [command, target] = positional;
     if (local && command !== 'update') throw new Error('--local is only supported by update.');
+    if (command !== 'install' && (install.name || install.port || install.user || !install.domains || install.yes)) {
+      throw new Error('--name, --port, --user, --no-domains and --yes are install options.');
+    }
     let result;
-    if (command === 'init' && positional.length <= 2) {
+    if (command === 'install' && positional.length === 1) {
+      const done = await installService({ cwd, dryRun, ...install });
+      if (done.dryRun) {
+        console.log(`Planned service orionplace-${done.name} on 127.0.0.1:${done.port} as ${done.user}`);
+        console.log(`Domains: ${done.frontends.join(', ') || 'none yet'} -> ${done.backend || 'no backend yet'}`);
+        console.log(`\n${done.unitPath}:\n${done.unit}`);
+      } else {
+        console.log(`\nInstalled orionplace-${done.name} (port ${done.port}, user ${done.user}).`);
+        for (const domain of done.frontends) {
+          if (!done.connected) console.log(`  - ${domain}: not connected to nginx (see above)`);
+          else if (done.failed.includes(domain)) console.log(`  ✗ ${domain}: not connected (see above)`);
+          else console.log(`  ✓ https://${domain}`);
+        }
+        if (done.failed.length) console.log('Fix the problems above, then run: sudo orionplace domain add <domain>');
+        console.log(`Manage it with: orionplace app status ${done.name} | orionplace app logs ${done.name}`);
+        console.log('After code changes or npx orionplace-nuxt update, run sudo npx orionplace-nuxt install again.');
+      }
+    } else if (command === 'init' && positional.length <= 2) {
       result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
     } else if (command === 'update' && positional.length === 1) {
       result = await updateProject({ cwd, dryRun, local });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-nuxt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Nuxt 4 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",

package/src/install.mjs

@@ -0,0 +1,355 @@
+// Installs the built storefront as a system service on a Linux server and
+// connects its domains through the "orionplace" server tool
+// (https://orionmarket.place/downloads/orionplace.sh) when that tool is set up.
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { request } from 'node:http';
+import { createServer } from 'node:net';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { setupProject } from './setup.mjs';
+
+export const framework = {
+  id:          'nuxt',
+  title:       'Nuxt',
+  dependency:  'nuxt',
+  output:      '.output/server/index.mjs',
+  start:       () => ['.output/server/index.mjs'],
+  environment: {},
+};
+
+export const defaultPaths = {
+  etc:     process.env.ORIONPLACE_ETC || '/etc/orionplace',
+  systemd: '/etc/systemd/system',
+  openrc:  '/etc/init.d',
+  logs:    '/var/log/orionplace',
+  srv:     '/srv/orionplace',
+  tool:    ['/usr/local/bin/orionplace', '/usr/bin/orionplace'],
+};
+
+const SERVICE_USER = 'orionplace';
+
+// run(command, args, { cwd, capture, env }) -> { code, output }
+export function runCommand(command, args, { cwd, capture = false, env = process.env } = {}) {
+  return new Promise((done, reject) => {
+    const child  = spawn(command, args, { cwd, env, stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+    let output   = '';
+    if (capture) {
+      child.stdout.on('data', chunk => { output += chunk; });
+      child.stderr.on('data', chunk => { output += chunk; });
+    }
+    child.once('error', reject);
+    child.once('exit', code => done({ code: code ?? 1, output }));
+  });
+}
+
+function parseConf(text) {
+  const values = {};
+  for (const line of text.split('\n')) {
+    const match = /^([A-Z_]+)=(.*)$/.exec(line);
+    if (match) values[match[1]] = match[2];
+  }
+  return values;
+}
+
+export async function readApps(paths = defaultPaths) {
+  const directory = join(paths.etc, 'apps');
+  let names       = [];
+  try { names = (await readdir(directory)).filter(name => name.endsWith('.conf')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const apps      = [];
+  for (const name of names) apps.push(parseConf(await readFile(join(directory, name), 'utf8')));
+  return apps;
+}
+
+export function serviceName(value) {
+  const name = value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error('Choose a service name with letters, digits and dashes: --name shop');
+  return name;
+}
+
+function portIsFree(port) {
+  return new Promise(done => {
+    const server = createServer();
+    server.once('error', () => done(false));
+    server.listen({ port, host: '127.0.0.1', exclusive: true }, () => server.close(() => done(true)));
+  });
+}
+
+export async function choosePort(apps, wanted, isFree = portIsFree) {
+  const taken = new Set(apps.map(app => Number(app.PORT)));
+  if (wanted) {
+    if (!Number.isInteger(wanted) || wanted < 1024 || wanted > 65535) throw new Error('Use a port between 1024 and 65535.');
+    return wanted;
+  }
+  for (let port = 3000; port < 4000; port++) {
+    if (!taken.has(port) && await isFree(port)) return port;
+  }
+  throw new Error('No free port between 3000 and 3999. Choose one with --port.');
+}
+
+async function passwdEntry(user) {
+  const text = await readFile('/etc/passwd', 'utf8');
+  for (const line of text.split('\n')) {
+    const [name, , uid, gid, , home] = line.split(':');
+    if (name === user) return { name, uid: Number(uid), gid: Number(gid), home };
+  }
+  return null;
+}
+
+async function userByUid(uid) {
+  const text = await readFile('/etc/passwd', 'utf8');
+  for (const line of text.split('\n')) {
+    const [name, , id, gid, , home] = line.split(':');
+    if (Number(id) === uid && name) return { name, uid, gid: Number(gid), home };
+  }
+  return null;
+}
+
+// Every parent folder must let the service user through.
+async function checkReachable(root, account) {
+  let cursor = dirname(root);
+  while (true) {
+    const info = await stat(cursor);
+    const open = info.uid === account.uid ? info.mode & 0o100 : info.gid === account.gid ? info.mode & 0o010 : info.mode & 0o001;
+    if (!open) {
+      throw new Error(`The folder ${cursor} is closed to the service user ${account.name}. Move the storefront to ${defaultPaths.srv}/ (for example ${defaultPaths.srv}/${basename(root)}) and run install there.`);
+    }
+    if (cursor === dirname(cursor)) return;
+    cursor = dirname(cursor);
+  }
+}
+
+async function writeAtomic(path, content, mode = 0o644) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.orionplace-${process.pid}.tmp`;
+  await writeFile(temporary, content, { mode });
+  await rename(temporary, path);
+}
+
+export function systemdUnit({ name, root, user, group, port, node, env }) {
+  const environment = Object.entries({ NODE_ENV: 'production', HOST: '127.0.0.1', PORT: String(port), SITEMAPS_DIR: join(root, 'sitemaps'), ...env })
+    .map(([key, value]) => `Environment=${key}=${value}`).join('\n');
+  const args        = [...(existsSync(join(root, '.env')) ? ['--env-file=.env'] : []), ...framework.start(port)];
+  return `# Installed by "orionplace-${framework.id} install". Run it again after changes;
+# manage with: orionplace app status|logs|restart ${name}
+[Unit]
+Description=OrionMarketplace storefront ${name} (${framework.title})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+Group=${group}
+WorkingDirectory=${root}
+${environment}
+ExecStart=${node} ${args.join(' ')}
+Restart=on-failure
+RestartSec=3
+LimitNOFILE=65535
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+export function openrcScript({ name, root, user, group, port, node, env, logs }) {
+  const environment = Object.entries({ NODE_ENV: 'production', HOST: '127.0.0.1', PORT: String(port), SITEMAPS_DIR: join(root, 'sitemaps'), ...env })
+    .map(([key, value]) => `export ${key}="${value}"`).join('\n');
+  const args        = [...(existsSync(join(root, '.env')) ? ['--env-file=.env'] : []), ...framework.start(port)];
+  return `#!/sbin/openrc-run
+# Installed by "orionplace-${framework.id} install". Run it again after changes;
+# manage with: orionplace app status|logs|restart ${name}
+name="orionplace-${name}"
+description="OrionMarketplace storefront ${name} (${framework.title})"
+supervisor=supervise-daemon
+respawn_delay=3
+command="${node}"
+command_args="${args.join(' ')}"
+command_user="${user}:${group}"
+directory="${root}"
+output_log="${logs}/${name}.log"
+error_log="${logs}/${name}.log"
+${environment}
+
+depend() {
+  need net
+  after firewall
+}
+
+start_pre() {
+  checkpath --directory --owner ${user}:${group} --mode 0755 ${logs}
+}
+`;
+}
+
+async function prompt(question) {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await terminal.question(question)).trim(); }
+  finally { terminal.close(); }
+}
+
+function log(message) { console.log(message); }
+
+// /usr/local/bin/node from the server tool follows Node.js updates; the
+// versioned path of the running binary would not.
+function stableNode() {
+  return ['/usr/local/bin/node', '/usr/bin/node'].find(path => existsSync(path)) || process.execPath;
+}
+
+// Fills in the backend and first storefront domain when the project has none.
+async function ensureDomains(root, { yes }) {
+  const read     = async () => JSON.parse(await readFile(join(root, 'orionplace/settings.json'), 'utf8'));
+  let settings   = await read();
+  const ask      = process.stdin.isTTY && !yes;
+  if (!settings.backend) {
+    if (!ask) throw new Error(`Set the personal backend first: npx orionplace-${framework.id} set backend my-shop.orionplace.app`);
+    log('Your personal backend is shown in your orionmarket.place profile, for example my-shop.orionplace.app.');
+    await setupProject({ cwd: root, field: 'backend', value: await prompt('Personal backend domain: ') });
+    settings = await read();
+  }
+  if (!settings.frontends?.length) {
+    if (!ask) throw new Error(`Add the storefront domain first: npx orionplace-${framework.id} add frontend shop.example.com`);
+    await setupProject({ cwd: root, action: 'add', field: 'frontend', value: await prompt('Storefront domain (for example shop.example.com): ') });
+    settings = await read();
+  }
+  return settings;
+}
+
+// The storefront's home page as the public domain sees it -> HTTP status, 0 when down.
+function homeStatus(port, host) {
+  return new Promise(done => {
+    const call = request({ host: '127.0.0.1', port, path: '/', headers: { host }, timeout: 15000 }, response => {
+      response.resume();
+      done(response.statusCode);
+    });
+    call.once('timeout', () => call.destroy());
+    call.once('error', () => done(0));
+    call.end();
+  });
+}
+
+async function waitForHttp(port, host, seconds = 90) {
+  const until = Date.now() + seconds * 1000;
+  while (Date.now() < until) {
+    const status = await homeStatus(port, host);
+    if (status) return status;
+    await new Promise(done => setTimeout(done, 1000));
+  }
+  return 0;
+}
+
+export async function installService({
+  cwd = process.cwd(), name, port, user, build = true, domains = true, yes = false, dryRun = false,
+  paths = defaultPaths, run = runCommand, uid = process.getuid?.(), isFree = portIsFree,
+  systemd = existsSync('/run/systemd/system'), node = stableNode(),
+} = {}) {
+  if (process.platform !== 'linux') throw new Error('install sets up a Linux server service. Run it on your VPS.');
+  if (uid !== 0 && !dryRun) throw new Error(`install needs root: sudo npx orionplace-${framework.id} install`);
+  const root     = resolve(cwd);
+  if (!/^\/[A-Za-z0-9._/@+-]+$/.test(root)) throw new Error(`Use a storefront folder path without spaces or special characters (for example ${paths.srv}/shop), not ${root}.`);
+  let pkg;
+  try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')); }
+  catch { throw new Error(`Run install in your storefront folder (created with: npx orionplace-${framework.id} init).`); }
+  if (!{ ...pkg.devDependencies, ...pkg.dependencies }[framework.dependency] || !existsSync(join(root, 'orionplace/settings.json'))) {
+    throw new Error(`This folder is not an Orionplace ${framework.title} storefront. Run install in the folder created with: npx orionplace-${framework.id} init`);
+  }
+  const openrc   = !systemd && existsSync('/sbin/openrc-run');
+  if (!systemd && !openrc && !dryRun) throw new Error('Neither systemd nor OpenRC was found; start the storefront with your own process manager (see orionplace/README.md, Deploy on your VPS).');
+
+  const settings = dryRun ? JSON.parse(await readFile(join(root, 'orionplace/settings.json'), 'utf8')) : await ensureDomains(root, { yes });
+  const apps     = await readApps(paths);
+  const previous = apps.find(app => app.DIR === root);
+  const service  = serviceName(name || previous?.NAME || basename(root));
+  if (apps.some(app => app.NAME === service && app.DIR !== root)) {
+    throw new Error(`Another storefront already uses the name ${service} (${apps.find(app => app.NAME === service).DIR}). Choose one with --name.`);
+  }
+  const chosen   = await choosePort(apps.filter(app => app.DIR !== root), port ? Number(port) : Number(previous?.PORT) || 0, isFree);
+
+  // The service runs as the folder's owner, or as "orionplace" for root-owned folders.
+  const owner    = await stat(root);
+  let account    = user ? await passwdEntry(user) : owner.uid === 0 ? await passwdEntry(SERVICE_USER) : await userByUid(owner.uid);
+  if (user && !account) throw new Error(`No system user ${user}.`);
+  if (!account && !dryRun) {
+    if (existsSync('/usr/sbin/useradd') || existsSync('/sbin/useradd')) {
+      await run('useradd', ['--system', '--home-dir', paths.srv, '--shell', '/sbin/nologin', '--user-group', SERVICE_USER], { capture: true });
+    } else {
+      await run('addgroup', ['-S', SERVICE_USER], { capture: true });
+      await run('adduser', ['-S', '-D', '-H', '-h', paths.srv, '-s', '/sbin/nologin', '-G', SERVICE_USER, SERVICE_USER], { capture: true });
+    }
+    account = await passwdEntry(SERVICE_USER);
+    if (!account) throw new Error(`Could not create the system user ${SERVICE_USER}.`);
+  }
+  account      ||= { name: SERVICE_USER, uid: -1, gid: -1 };
+  const group    = account.gid >= 0 ? (await readFile('/etc/group', 'utf8')).split('\n').map(line => line.split(':'))
+    .find(([, , gid]) => Number(gid) === account.gid)?.[0] || account.name : account.name;
+  if (account.uid >= 0) await checkReachable(root, account);
+
+  const values   = { name: service, root, user: account.name, group, port: chosen, node, env: framework.environment, logs: paths.logs };
+  const unitPath = systemd ? join(paths.systemd, `orionplace-${service}.service`) : join(paths.openrc, `orionplace-${service}`);
+  const unit     = systemd ? systemdUnit(values) : openrcScript(values);
+  const conf     = [
+    `# Managed by orionplace-${framework.id} install. Use "orionplace app" commands to change it.`,
+    `NAME=${service}`, `FRAMEWORK=${framework.id}`, `DIR=${root}`, `PORT=${chosen}`,
+    `USER=${account.name}`, `NODE=${node}`, `SERVICE=orionplace-${service}`, '',
+  ].join('\n');
+  if (dryRun) {
+    return { dryRun, name: service, port: chosen, user: account.name, unitPath, unit, conf, frontends: settings.frontends || [], backend: settings.backend };
+  }
+
+  log(`\n==> Building the ${framework.title} storefront ${service}`);
+  // The website build; ORIONPLACE_APP_ORIGIN would make the Android app build.
+  const buildEnv = { ...process.env };
+  delete buildEnv.ORIONPLACE_APP_ORIGIN;
+  if (!existsSync(join(root, 'node_modules', framework.dependency))) {
+    const installed = await run('npm', ['install', '--no-audit', '--no-fund'], { cwd: root, env: buildEnv });
+    if (installed.code) throw new Error('npm install failed; see the messages above.');
+  }
+  if (build || !existsSync(join(root, framework.output))) {
+    const built = await run('npm', ['run', 'build'], { cwd: root, env: buildEnv });
+    if (built.code) throw new Error('The build failed; see the messages above. The running service (if any) was not changed.');
+  }
+  if (!existsSync(join(root, framework.output))) throw new Error(`The build did not produce ${framework.output}.`);
+  const owned    = await run('chown', ['-R', `${account.uid}:${account.gid}`, root], { capture: true });
+  if (owned.code) throw new Error(`Could not give ${root} to ${account.name}:\n${owned.output}`);
+
+  log(`\n==> Installing the service orionplace-${service} on port ${chosen}`);
+  await writeAtomic(unitPath, unit, systemd ? 0o644 : 0o755);
+  await writeAtomic(join(paths.etc, 'apps', `${service}.conf`), conf);
+  const steps    = systemd
+    ? [['systemctl', ['daemon-reload']], ['systemctl', ['enable', `orionplace-${service}`]], ['systemctl', ['restart', `orionplace-${service}`]]]
+    : [['rc-update', ['add', `orionplace-${service}`, 'default']], ['rc-service', [`orionplace-${service}`, 'restart']]];
+  for (const [command, args] of steps) {
+    const result = await run(command, args, { capture: true });
+    if (result.code) throw new Error(`${command} ${args.join(' ')} failed:\n${result.output}`);
+  }
+  const status   = await waitForHttp(chosen, settings.frontends[0]);
+  if (!status) {
+    const logs = systemd
+      ? await run('journalctl', ['-u', `orionplace-${service}`, '-n', '40', '--no-pager'], { capture: true })
+      : await run('tail', ['-n', '40', join(paths.logs, `${service}.log`)], { capture: true });
+    throw new Error(`The storefront did not start on port ${chosen}. Last log lines:\n${logs.output}`);
+  }
+  log(`  ✓ orionplace-${service} answers on 127.0.0.1:${chosen} (HTTP ${status})`);
+
+  const tool     = paths.tool.find(path => existsSync(path));
+  const failed   = [];
+  if (domains && tool) {
+    for (const domain of settings.frontends) {
+      log(`\n==> Connecting ${domain}`);
+      const backend = settings.backend.replace(/^https:\/\//, '').replace(/\/api$/, '');
+      const result  = await run(tool, ['domain', 'add', domain, '--app', service, '--backend', backend, '--yes']);
+      if (result.code) failed.push(domain);
+    }
+  } else if (domains) {
+    log('\nThe orionplace server tool is not set up, so nginx and HTTPS were not configured. Prepare the server:');
+    log('  curl -fsSLo orionplace.sh https://orionmarket.place/downloads/orionplace.sh && sudo sh orionplace.sh setup');
+    log(`Then run this install again. Or proxy your HTTPS site to http://127.0.0.1:${chosen} as orionplace/README.md describes.`);
+  }
+  return { name: service, port: chosen, user: account.name, unitPath, frontends: settings.frontends, failed, connected: domains && Boolean(tool) };
+}

package/src/project-readme.mjs

@@ -513,6 +513,13 @@ If installation fails after source generation, run \`npm install\` and retry.
 
 ## Deploy on your VPS
 
+The quickest way: prepare the server with the OrionMarketplace server script,
+then run \`sudo npx orionplace-nuxt install\` in this folder. It builds the
+project, runs it as a system service and connects your domains with nginx and
+HTTPS. Steps: [Install a storefront](https://orionmarket.place/en/sandbox/install/storefront).
+
+To set the server up yourself instead:
+
 This integration needs a Node.js server and its domain configuration files.
 It does not support static-only or edge hosting. Deploy the build, dependencies,
 \`sitemaps\`, and your environment configuration together; use an absolute

package/templates/app/utils/orionplace/api.ts

@@ -190,8 +190,8 @@ export class OrionplaceApi {
     const body             = response.body as {
       page_data?: { csrf?: boolean };
     } | null;
-    // Only a CSRF rejection permits one automatic retry: Django views answer
-    // 419, API endpoints answer 403 with page_data.csrf set to false.
+    // A CSRF rejection: Django views answer 419, API endpoints answer 403
+    // with page_data.csrf set to false. The request is not repeated.
     const csrfRejected     =
       response.status === 419 ||
       (response.status === 403 && body?.page_data?.csrf === false);