orionplace-react 0.7.7 → 0.8.0

package/src/project-readme.mjs

@@ -1,442 +0,0 @@
-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 home
-page should show the configured catalog and storefront content. If it shows the
-initialization error state, check the domain mapping and backend response.
-
-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/page.tsx\`, \`../${base}app/*/page.tsx\` | Server-rendered public and account storefront routes. |
-| \`../${base}app/_storefront/\` | Route controllers that connect components, navigation and API actions. |
-| \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
-| \`../${base}app/ps3/blog/[...orionplace]/route.ts\` | The route handler serving guarded blog images and videos under \`/ps3/blog/...\`. |
-| \`../${base}app/robots.txt/route.ts\`, \`../${base}app/sitemap.xml/route.ts\` | \`/robots.txt\` and the storefront sitemap. |
-| \`../${base}proxy.ts\` | Marks personalized pages private and answers HTTP 503 when Application Load fails. |
-| \`../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.
-
-## Import aliases
-
-Application imports use \`@/\`. In \`tsconfig.json\`, merge these entries into
-\`compilerOptions.paths\` while keeping your other settings:
-
-\`\`\`json
-{
-  "@/*": ["./${base}*"],
-  "@orionplace-runtime/*": ["./orionplace/runtime/*"]
-}
-\`\`\`
-
-The \`@/\` alias follows this project's \`${base || '.'}\` source layout. The gateway alias
-points to the project-root \`orionplace/runtime/\` directory. Setup writes
-these mappings for new projects and updates unchanged generated configuration.
-If you already own \`tsconfig.json\`, it is preserved; merge these aliases before
-starting the application. Imports then work at any component directory depth.
-
-## 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":false,"detalize_mode":"light"}'
-\`\`\`
-
-Check both the HTTP status and \`form_errors\`. Successful initialization returns
-\`page_data\`; HTTP 200 by itself is insufficient. Public storefront requests do
-not require a login prompt. Protected actions still require backend permission.
-
-## Application Load architecture
-
-The root layout initializes the marketplace before your page renders. The request
-uses \`POST /api/appload\` with \`ignore_cache: false\`.
-Tenant settings may override these options.
-
-| Project file | Responsibility |
-| --- | --- |
-| \`${base}app/layout.tsx\` | Awaits initialization, then passes the snapshot to the provider. |
-| \`${base}app/StorefrontShell.tsx\` | Shows initialization failures and mounts storefront content after success. |
-| \`${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}stores/orionplaceSelections.ts\` | Current locale, currency and unit choices. |
-| \`${base}stores/orionplaceCatalog.ts\` | Categories and subscription plans from initialization or later requests. |
-| \`${base}stores/orionplaceProducts.ts\` | Product collections, confirmed updates and customer counters. |
-| \`${base}stores/orionplaceBrowse.ts\` | Search choices, selected filters and journal results. |
-| \`${base}stores/orionplaceScope.ts\` | Creates and synchronizes the stores before child components render. |
-| \`${base}providers/OrionplaceProvider.tsx\` | Provides one coordinated store scope per browser session. |
-| \`${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">Application Load: {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. The \`@/\` alias resolves
-to the source root configured above, so imports work in nested component folders.
-
-| 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. Some endpoint descriptions may be omitted.
-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.
-
-### Storefront pages
-
-Navigation hides categories with \`exclude_from_tree: true\` and their descendants.
-The full published tree remains available for product category lookup and breadcrumbs.
-
-The maintained components and routes cover catalog and search, product details,
-variants, journal, directories, contact, tariffs and the customer's account flows.
-Public events and banner images come from Application Load. Page metadata follows
-client navigation and the selected language.
-
-A signed-in request that receives HTTP \`401\` removes private account values and
-refreshes Application Load as a guest while retaining public data and selections.
-The failed request is not repeated and no sign-in dialog opens automatically.
-
-### 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 Application Load 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\`, or HTTP \`403\` with \`page_data.csrf: false\`, means CSRF
-rejection. A \`403\` without that flag can mean permissions or origin rejection.
-The shared client renews the token for the next action and returns the failed
-request; the customer retries explicitly. After confirmed login/logout, reset and refresh Application Load; these actions
-change application data and do not log in/out or delete cookies.
-
-[Cookie lifecycle and browser request example](https://orionmarket.place/en/sandbox/appload/react#session-cookies)
-
-### Rendering, navigation and failures
-
-Each server render gets its own request-scoped snapshot; the provider creates one
-coordinated store scope per browser session and hydrates every store from that
-snapshot, so hydration and client navigation do not repeat initialization.
-Concurrent \`load\` calls share one request per scope.
-
-Failures also survive hydration and navigation. They never open a login modal or
-trigger an automatic retry on every route. The supplied shell shows
-\`StorefrontErrorPage\` and keeps the header, route content and footer unmounted
-until initialization succeeds. Retry reloads the page; an unknown address keeps
-the 404 page. App Router pages cannot change their status once they stream, so
-\`${base}proxy.ts\` starts Application Load for a full page load and hands it
-to the render (still one request): when it fails, the error page is sent with
-HTTP 503. A project that keeps its own \`proxy.ts\` sends it with HTTP 200 unless
-it does the same. 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
-storefront does not render account keys or backend exception stacks.
-
-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
-
-The quickest way: prepare the server with the OrionMarketplace server script,
-then run \`sudo npx orionplace-react 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?framework=react).
-Then manage it from this folder: \`npx orionplace-react status\`, \`sudo npx orionplace-react restart\`,
-\`sudo npx orionplace-react stop\`, \`sudo npx orionplace-react start\` and \`sudo npx orionplace-react logs\`.
-\`sudo npx orionplace-react uninstall\` (or \`cleanup\`) stops and removes the service; this folder stays.
-
-To set the server up yourself instead:
-
-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. \`/robots.txt\` points
-crawlers to \`/sitemap.xml\`, which lists the public pages, categories, products
-on sale and journal publications in every storefront language (each publication
-only in the languages it is written in). The sitemap is built from the backend
-and kept for an hour in \`node_modules/.cache/orionplace/sitemaps/\`
-(\`ORIONPLACE_CACHE_DIR\` moves it). After you publish or change content, rebuild
-it at once from the project folder; the running storefront serves the new
-sitemap without a restart:
-
-\`\`\`bash
-npm run orionplace:sitemap                          # every frontend domain
-npx orionplace-react sitemap rebuild shop.example.com  # one domain
-npx orionplace-react sitemap status                  # when each was built
-\`\`\`
-
-To keep a demo or staging storefront's shop pages out of search engines, set
-\`ORIONPLACE_NOINDEX_PATHS\` in \`.env\` to path prefixes separated by spaces,
-for example \`ORIONPLACE_NOINDEX_PATHS="/catalog /category /product"\`. Those
-pages answer with \`X-Robots-Tag: noindex, follow\` and the sitemap leaves them
-out; the journal and other pages stay indexable. Leave it empty on a live shop.
-
-Every product page carries schema.org product data for Google and Yandex: the
-price, the crossed-out old price, stock, photos, brand, seller, rating and the
-return terms the page shows. The return terms name the shop's shipping
-countries, which Application Load sends in \`init.shipping_countries\`; without
-a shipping country they are left out. The delivery cost is not included: it
-depends on the buyer's address.
-
-This setup does not add analytics.
-
-## Android app
-
-Deploy the website first, then build the app with Capacitor 8. With
-\`ORIONPLACE_APP_ORIGIN\` set to your public storefront (HTTPS) the build is
-client-only and sends every API request to that storefront through Capacitor's
-native HTTP (\`lib/orionplace/nativeApp.ts\`). Without the variable the
-website build is unchanged. Steps:
-[Android app guide](https://orionmarket.place/en/sandbox/android-app?framework=react).
-
-\`\`\`bash
-ORIONPLACE_APP_ORIGIN=https://shop.example.com npx next build
-npx cap sync android
-\`\`\`
-
-## More documentation
-
-- [React package installation and domain setup](https://orionmarket.place/en/sandbox/new-project/react)
-- [Application Load](https://orionmarket.place/en/sandbox)
-`;
-}

package/src/service.mjs

@@ -1,186 +0,0 @@
-// Manages the storefront service that "install" set up: start, stop, restart,
-// status, logs and the list of every storefront service on this server.
-// The service is found by its folder (the project root) or by --name.
-import { existsSync } from 'node:fs';
-import { readFile, rm } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-import { defaultPaths, framework, homeStatus, readApps, runCommand, waitForHttp } from './install.mjs';
-
-export const SERVICE_ACTIONS = ['start', 'stop', 'restart', 'status', 'logs', 'list', 'uninstall'];
-// "cleanup" is another name for uninstall.
-export const SERVICE_ALIASES = { cleanup: 'uninstall' };
-
-async function frontends(dir) {
-  try { return JSON.parse(await readFile(join(dir, 'orionplace/settings.json'), 'utf8')).frontends || []; }
-  catch { return []; }
-}
-
-// The registered storefront of this folder, or the one named with --name.
-export async function findApp({ cwd = process.cwd(), name, paths = defaultPaths } = {}) {
-  const apps = await readApps(paths);
-  const root = resolve(cwd);
-  const app  = name ? apps.find(item => item.NAME === name) : apps.find(item => item.DIR === root);
-  if (app) return app;
-  const known = apps.map(item => item.NAME).join(', ');
-  if (name) throw new Error(`No storefront service named ${name}.${known ? ` Installed: ${known}.` : ''}`);
-  throw new Error(`${root} is not installed as a service. Install it first: sudo npx orionplace-${framework.id} install`
-    + (known ? `\nOr name another storefront: --name ${apps[0].NAME} (installed: ${known})` : ''));
-}
-
-// true / false; "unknown" when neither systemd nor OpenRC answers.
-async function isRunning(service, { run, systemd }) {
-  const result = systemd
-    ? await run('systemctl', ['is-active', '--quiet', service], { capture: true })
-    : await run('rc-service', [service, 'status'], { capture: true });
-  return result.code === 0;
-}
-
-async function isEnabled(service, { run, systemd }) {
-  const result = systemd
-    ? await run('systemctl', ['is-enabled', '--quiet', service], { capture: true })
-    : await run('rc-update', ['show', 'default'], { capture: true });
-  return systemd ? result.code === 0 : new RegExp(`^\\s*${service}\\s`, 'm').test(result.output);
-}
-
-async function lastLogs(app, { run, systemd, paths, lines = 40 }) {
-  const result = systemd
-    ? await run('journalctl', ['-u', app.SERVICE || `orionplace-${app.NAME}`, '-n', String(lines), '--no-pager'], { capture: true })
-    : await run('tail', ['-n', String(lines), join(paths.logs, `${app.NAME}.log`)], { capture: true });
-  return result.output;
-}
-
-// One storefront's state: service, autostart, and the home page as its first domain sees it.
-export async function serviceStatus(app, { run = runCommand, systemd = existsSync('/run/systemd/system'), probe = homeStatus } = {}) {
-  const service = app.SERVICE || `orionplace-${app.NAME}`;
-  const domains = await frontends(app.DIR);
-  const running = await isRunning(service, { run, systemd });
-  const enabled = await isEnabled(service, { run, systemd });
-  const http    = running ? await probe(Number(app.PORT), domains[0] || 'localhost') : 0;
-  return { name: app.NAME, service, framework: app.FRAMEWORK, dir: app.DIR, port: Number(app.PORT), running, enabled, http, domains };
-}
-
-/**
- * controlService({ action, cwd, name, lines, follow }) runs one action and
- * returns what happened; logs and follow print straight to the terminal.
- */
-export async function controlService({
-  action, cwd = process.cwd(), name, lines = 100, follow = false,
-  paths = defaultPaths, run = runCommand, uid = process.getuid?.(),
-  systemd = existsSync('/run/systemd/system'), openrc = existsSync('/sbin/openrc-run'),
-  platform = process.platform, probe = homeStatus, wait = waitForHttp, dryRun = false,
-} = {}) {
-  action = SERVICE_ALIASES[action] || action;
-  if (!SERVICE_ACTIONS.includes(action)) throw new Error(`Unknown service command ${action}. Use ${SERVICE_ACTIONS.join(', ')}.`);
-  if (platform !== 'linux') throw new Error(`${action} manages the Linux service that install set up. Run it on your server.`);
-  if (!systemd && !openrc) throw new Error('Neither systemd nor OpenRC was found on this server.');
-
-  if (action === 'list') {
-    const apps = await readApps(paths);
-    return { action, apps: await Promise.all(apps.map(app => serviceStatus(app, { run, systemd, probe }))) };
-  }
-
-  const app     = await findApp({ cwd, name, paths });
-  const service = app.SERVICE || `orionplace-${app.NAME}`;
-  if (action === 'status') return { action, ...await serviceStatus(app, { run, systemd, probe }) };
-
-  if (action === 'logs') {
-    const count = Number(lines);
-    if (!Number.isInteger(count) || count < 1) throw new Error('Give the number of log lines as a whole number, for example: logs 200');
-    const args  = systemd
-      ? ['journalctl', ['-u', service, '-n', String(count), '--no-pager', ...(follow ? ['--follow'] : [])]]
-      : ['tail', ['-n', String(count), ...(follow ? ['-F'] : []), join(paths.logs, `${app.NAME}.log`)]];
-    const result = await run(...args);
-    if (result.code) throw new Error(`${args[0]} could not read the logs of ${service}${uid !== 0 ? `; try: sudo npx orionplace-${framework.id} logs` : ''}.`);
-    return { action, name: app.NAME, service };
-  }
-
-  if (action === 'uninstall') return uninstallService(app, { paths, run, uid, systemd, name, dryRun });
-  if (uid !== 0) throw new Error(`${action} needs root: sudo npx orionplace-${framework.id} ${action}${name ? ` --name ${name}` : ''}`);
-  const result  = systemd
-    ? await run('systemctl', [action, service], { capture: true })
-    : await run('rc-service', [service, action], { capture: true });
-  if (result.code) throw new Error(`Could not ${action} ${service}:\n${result.output.trim()}`);
-  if (action === 'stop') return { action, name: app.NAME, service, running: false };
-
-  const domains = await frontends(app.DIR);
-  const http    = await wait(Number(app.PORT), domains[0] || 'localhost', 90);
-  if (!http) {
-    throw new Error(`${service} did not answer on port ${app.PORT} within 90 seconds. Last log lines:\n${await lastLogs(app, { run, systemd, paths })}`);
-  }
-  return { action, name: app.NAME, service, port: Number(app.PORT), running: true, http, domains };
-}
-
-/**
- * Stops the service, removes it from autostart, deletes its unit or init
- * script and its registration. The project folder and its build stay. With
- * the orionplace server tool, "orionplace app remove" does it and also turns
- * the storefront's domains into a placeholder page.
- */
-async function uninstallService(app, { paths, run, uid, systemd, name, dryRun }) {
-  const service  = app.SERVICE || `orionplace-${app.NAME}`;
-  const unitPath = systemd ? join(paths.systemd, `${service}.service`) : join(paths.openrc, service);
-  const confPath = join(paths.etc, 'apps', `${app.NAME}.conf`);
-  const tool     = (paths.tool || []).find(path => existsSync(path));
-  const result   = { action: 'uninstall', name: app.NAME, service, dir: app.DIR, domains: await frontends(app.DIR), tool: Boolean(tool), unitPath, confPath, dryRun };
-  if (dryRun) return result;
-  if (uid !== 0) throw new Error(`uninstall needs root: sudo npx orionplace-${framework.id} uninstall${name ? ` --name ${name}` : ''}`);
-  if (tool) {
-    const removed = await run(tool, ['app', 'remove', app.NAME, '--yes']);
-    if (removed.code) throw new Error(`orionplace app remove ${app.NAME} failed; see the messages above.`);
-    return result;
-  }
-  // A service that is already stopped or missing is fine: the goal is that it is gone.
-  if (systemd) await run('systemctl', ['disable', '--now', service], { capture: true });
-  else {
-    await run('rc-service', [service, 'stop'], { capture: true });
-    await run('rc-update', ['del', service, 'default'], { capture: true });
-  }
-  await rm(unitPath, { force: true });
-  if (systemd) await run('systemctl', ['daemon-reload'], { capture: true });
-  await rm(confPath, { force: true });
-  return result;
-}
-
-// The CLI output of controlService; returns the process exit code.
-export function printService(result, log = console.log) {
-  const line = item => {
-    const state = item.running ? (item.http ? `running, home page HTTP ${item.http}` : 'running, home page does not answer') : 'stopped';
-    return `${item.name.padEnd(16)} ${String(item.framework || '').padEnd(7)} ${String(item.port).padEnd(6)} ${state}`;
-  };
-  if (result.action === 'list') {
-    if (!result.apps.length) {
-      log(`No storefront services on this server. Install one from its folder: sudo npx orionplace-${framework.id} install`);
-      return 0;
-    }
-    log(`${'NAME'.padEnd(16)} ${'TYPE'.padEnd(7)} ${'PORT'.padEnd(6)} STATE`);
-    for (const item of result.apps) log(line(item));
-    return 0;
-  }
-  if (result.action === 'status') {
-    log(`${result.service} (${result.framework || framework.id}) in ${result.dir}`);
-    log(`  Service:   ${result.running ? 'running' : 'stopped'}${result.enabled ? ', starts with the server' : ', does not start with the server'}`);
-    log(`  Port:      127.0.0.1:${result.port}`);
-    log(`  Home page: ${result.running ? (result.http ? `HTTP ${result.http}` : 'does not answer') : '-'}`);
-    for (const domain of result.domains) log(`  Domain:    https://${domain}`);
-    return result.running && result.http && result.http < 500 ? 0 : 3;
-  }
-  if (result.action === 'uninstall') {
-    if (result.dryRun) {
-      log(`Would stop and remove ${result.service}:`);
-      log(result.tool ? `  orionplace app remove ${result.name} --yes (also turns its domains into a placeholder)` : `  ${result.unitPath}\n  ${result.confPath}`);
-      log(`The project stays in ${result.dir}.`);
-      return 0;
-    }
-    log(`Removed the service ${result.service}. The project and its build stay in ${result.dir}; delete the folder when you no longer need it.`);
-    if (!result.tool && result.domains.length) {
-      log(`nginx still sends ${result.domains.join(', ')} to the stopped service; remove those sites from your nginx configuration.`);
-    }
-    log(`Install it again with: sudo npx orionplace-${framework.id} install`);
-    return 0;
-  }
-  if (result.action === 'stop') log(`Stopped ${result.service}.`);
-  else if (result.action === 'start' || result.action === 'restart') {
-    log(`${result.action === 'start' ? 'Started' : 'Restarted'} ${result.service}: home page HTTP ${result.http} on 127.0.0.1:${result.port}.`);
-  }
-  return 0;
-}