@luigisbox/luma 0.0.0-stage → 0.2.0

package/bin/luma.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// `yarn luma <tool> [args]`: Luma's tools, run on the integration repository
+// it is called from. The integration's package.json has one script for all of
+// them, and a tool Luma adds is there once Luma is updated:
+//
+//   "scripts": { "luma": "luma" }      the package's command (`node luma/bin/luma.mjs` with a submodule)
+//
+//   yarn luma                  the tools, and what each answers
+//   yarn luma tasks --headed   one of them, its own options after its name
+//
+// The integration's settings are its luma.config.mjs (`host`: the storefront's
+// host name, `site`, the fixtures…: bin/config.mjs), never the script: each
+// tool is run with LBX_SITE_DIR (this repository), LBX_SITE and LBX_HOST set
+// from them (the environment's own win), from the folder it expects
+// (bin/tools.mjs).
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.mjs';
+import { TOOLS, availableTools } from './tools.mjs';
+
+const LUMA = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+/** The tools this Luma has (the published package has no edge rig: bin/tools.mjs). */
+const HERE = availableTools((p) => existsSync(join(LUMA, p)));
+
+/**
+ * The steps `tool` runs: each a command, its arguments, its folder and its environment.
+ * @param {string} tool
+ * @param {string[]} args
+ * @param {{ site: string, luma?: string, env?: Record<string, string | undefined>, node?: string }} o
+ * @returns {{ cmd: string, args: string[], cwd: string, env: Record<string, string | undefined> }[] | null}
+ */
+export const commandFor = (tool, args, { site, luma = LUMA, env = {}, node = process.execPath }) => {
+  const t = TOOLS[tool];
+  if (!t) return null;
+  const given = args.length ? args : (t.args ?? []);
+  const fill = (v) => v.replaceAll('<host>', env.LBX_HOST ?? '');
+  const extra = Object.fromEntries(Object.entries(t.env ?? {}).map(([k, v]) => [k, process.env[k] ?? fill(v)]));
+  return t.run.map((step, i) => {
+    const last = i === t.run.length - 1;
+    const [cmd, ...rest] = Array.isArray(step) ? step : [node, join(luma, step)];
+    return { cmd, args: [...rest, ...(last ? given : [])], cwd: t.cwd === 'luma' ? luma : site, env: { ...env, ...extra } };
+  });
+};
+
+/**
+ * The environment the tools share: this repository, its site name and its storefront's host (its luma.config.mjs: bin/config.mjs).
+ * @param {string} site
+ * @param {Record<string, string | undefined>} [base]
+ * @returns {Promise<Record<string, string | undefined>>}
+ */
+export const siteEnv = async (site, base = process.env) => {
+  const config = await loadConfig(site, base);
+  return { ...base, LBX_SITE_DIR: base.LBX_SITE_DIR ?? site, LBX_SITE: config.site, ...(config.hostKnown ? { LBX_HOST: config.host } : {}) };
+};
+
+const list = () => {
+  const w = Math.max(...Object.keys(HERE).map((k) => k.length));
+  return `usage: yarn luma <tool> [its options]   (yarn luma <tool> --help: its options)\n\n${Object.entries(HERE)
+    .map(([k, t]) => `  ${k.padEnd(w)}  ${t.what}`)
+    .join('\n')}`;
+};
+
+// Run, not imported: through a symlink too (luma/ linked, npm's node_modules/.bin/luma)
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  const [tool, ...args] = process.argv.slice(2);
+  if (!tool || tool === '--help' || tool === '-h' || tool === 'help') {
+    console.log(list());
+    process.exit(0);
+  }
+  if (!HERE[tool]) {
+    console.error(`no tool "${tool}" in this Luma (bin/tools.mjs${TOOLS[tool] ? ': its files are not in this copy' : ''})\n\n${list()}`);
+    process.exit(2);
+  }
+  const site = resolve(process.env.LBX_SITE_DIR || process.cwd());
+  if (!existsSync(join(site, 'integration'))) {
+    console.error(`${site} is not an integration repository (no integration/): run yarn luma from one`);
+    process.exit(2);
+  }
+  // tooling sets the settings up (moves them from edge/rig.mjs, their older name): it runs without them
+  let env;
+  try {
+    env = tool === 'tooling' ? { ...process.env, LBX_SITE_DIR: process.env.LBX_SITE_DIR ?? site } : await siteEnv(site);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  if (!env.LBX_HOST && tool !== 'tooling' && tool !== 'baseline')
+    console.error(`note: no storefront host (luma.config.mjs \`export const host = '<www.shop.example>'\`, or LBX_HOST): the tools use the stub page (yarn luma tooling --write --host <name> sets it)`);
+  for (const s of commandFor(tool, args, { site, env })) {
+    const r = spawnSync(s.cmd, s.args, { cwd: s.cwd, env: s.env, stdio: 'inherit' });
+    if (r.error) {
+      console.error(`${s.cmd}: ${r.error.message}`);
+      process.exit(2);
+    }
+    if (r.status !== 0) process.exit(r.status ?? 1);
+  }
+}

package/bin/paths.mjs

@@ -0,0 +1,11 @@
+// Path checks the tools' local file servers share (chrome/run.mjs, tasks/run.mjs).
+import { sep } from 'node:path';
+
+/**
+ * Whether `file` is `dir` or inside it. Both normalized, absolute; `dir`
+ * without a trailing separator. A sibling whose name starts with `dir`'s
+ * (`dist-old` next to `dist`) is not inside it.
+ * @param {string} dir
+ * @param {string} file
+ */
+export const inside = (dir, file) => file === dir || file.startsWith(dir + sep);

package/bin/tools.mjs

@@ -0,0 +1,43 @@
+// Luma's tools for an integration repository, by name: what `yarn luma <tool>`
+// runs (bin/luma.mjs). A tool added here is there for every integration once
+// it updates @luigisbox/luma: nothing in the integration's package.json.
+// Tools whose files the package does not ship are not offered (availableTools).
+//
+//   run   in order, each must succeed: a script relative to luma/ (run with
+//         this Node), or a command as an array (['docker', 'compose', ...])
+//   cwd   'site': from the integration repository; 'luma': from luma/ (the edge rig's)
+//   args  the arguments when none are given (given ones go to the last step)
+//   env   set for it; `<host>` is the storefront's host
+//   what  one line: what it answers
+
+/** @type {Record<string, { run: (string | string[])[], cwd: 'site' | 'luma', args?: string[], env?: Record<string, string>, what: string }>} */
+export const TOOLS = {
+  chrome: { run: ['chrome/run.mjs'], cwd: 'site', what: "the live storefront in your Chrome with this integration on it, as a customer installs it (whether or not the site includes it yet)" },
+  tasks: { run: ['tasks/run.mjs'], cwd: 'site', what: 'our main-thread tasks over a frame (16 ms at 4x CPU) on the storefront, per scenario, by source line' },
+  footprint: { run: ['footprint/run.mjs'], cwd: 'site', what: 'what Luma weighs per page type: entry and round trips, scripts and bytes, chain, main thread, API requests, time to ready' },
+  perf: { run: ['edge/src/perf.mjs'], cwd: 'luma', what: "what Luma costs the site's pages, snippet off vs on (the edge rig running: rig-up, then rig or rig-stub)" },
+  a11y: { run: ['a11y/run.mjs'], cwd: 'site', what: 'WCAG 2.2 AA on our widgets, by keyboard too' },
+  parity: { run: ['parity/run.mjs'], cwd: 'site', what: "the site's own search and category UI against ours, scored" },
+  baseline: { run: ['build/baseline.mjs'], cwd: 'site', args: ['integration'], what: 'nothing newer than Baseline Widely available (--built dist: the build, dependencies included)' },
+  'rig-certs': { run: [['sh', 'edge/rig/certs.sh']], cwd: 'luma', what: "the rig's self-signed certificate for the storefront's host, once" },
+  'rig-up': { run: [['docker', 'compose', '-f', 'edge/rig/docker-compose.yml', 'up', '-d']], cwd: 'luma', what: "the edge rig's containers (Docker), once" },
+  'rig-down': { run: [['docker', 'compose', '-f', 'edge/rig/docker-compose.yml', 'down']], cwd: 'luma', what: "the edge rig's containers stopped" },
+  rig: { run: ['edge/build.mjs', 'edge/src/rig.mjs'], cwd: 'luma', env: { LBX_ORIGIN: 'https://<host>' }, what: 'the edge rig on the live storefront' },
+  'rig-stub': { run: ['edge/build.mjs', 'edge/src/rig.mjs'], cwd: 'luma', env: { LBX_ORIGIN: 'stub' }, what: "the edge rig on the integration's stub page" },
+  'rig-chrome': { run: ['edge/src/chrome.mjs'], cwd: 'luma', what: 'your Chrome on the rig: off | script | snippet | ssi | esi, and a path' },
+  'edge-test': { run: ['edge/test/rig.mjs'], cwd: 'luma', what: 'server-side rendering: the fault matrix, adoption, hydration (the rig on the stub page)' },
+  tooling: { run: ['build/tooling.mjs'], cwd: 'site', what: "this repository's setup for these tools: the luma script and the storefront's host" },
+};
+
+/**
+ * The files a tool runs, relative to luma/: its scripts, and a command's arguments that are paths.
+ * @param {{ run: (string | string[])[] }} t
+ * @returns {string[]}
+ */
+export const filesOf = (t) => t.run.flatMap((step) => (Array.isArray(step) ? step.slice(1).filter((a) => a.includes('/')) : [step]));
+
+/**
+ * The tools this Luma has: those whose files are all in it.
+ * @param {(path: string) => boolean} has  whether a path relative to luma/ exists
+ */
+export const availableTools = (has) => Object.fromEntries(Object.entries(TOOLS).filter(([, t]) => filesOf(t).every(has)));

package/build/baseline.d.mts

@@ -0,0 +1,8 @@
+// Types of build/baseline.mjs (the Baseline check) for the TS that imports it (Luma's tests).
+export declare const ALLOW: { feature: string; files: string[]; why: string }[];
+/** Lint a CSS string with the Baseline rule: the warnings' texts (`line:column text`), none when it passes. */
+export declare const lintCss: (code: string, name?: string) => Promise<string[]>;
+/** Lint files or folders (relative to `cwd`): prints the problems, resolves to their count. */
+export declare const check: (paths: string[], opts?: { cwd?: string; built?: boolean }) => Promise<number>;
+export declare const eslintConfig: (cwd: string, files: string[], built?: boolean) => Promise<unknown[]>;
+export declare const stylelintConfig: () => Record<string, unknown>;

package/build/baseline.mjs

@@ -0,0 +1,167 @@
+// The Baseline check (https://web.dev/baseline): Luma targets Baseline Widely
+// available, so what a page of ours runs must be in every major browser
+// (Chrome, Edge, Firefox, Safari, desktop and mobile) for at least 30 months.
+// A feature newer than that is used only behind a feature test, with a page
+// that works without it: those uses are the ALLOW list below.
+//
+//   yarn baseline                                                   (Luma's own sources and fixtures)
+//   node luma/build/baseline.mjs integration                        (an integration repository: `yarn luma baseline`)
+//   node luma/build/baseline.mjs --built dist                       (a build's output, dependencies included)
+//
+// JS and TS: ESLint with eslint-plugin-baseline-js (web-features data: syntax,
+// JS builtins and Web APIs, type-aware in .ts so `el.showPopover()` is seen).
+// CSS: Stylelint with stylelint-plugin-use-baseline (properties, values,
+// selectors, at-rules, functions, units; a use inside a matching `@supports`
+// passes). CSS inside TS strings is not linted here: Luma's own is checked by
+// its tests through `lintCss`.
+//
+// The tools are Luma's dependencies (README.md, "Browser support"). The plugins carry
+// their own snapshot of the Baseline data, so their versions are pinned: a
+// feature becomes Widely available here when the pin moves.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const LUMA = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Newer than Baseline Widely available, used only where feature-detected.
+ * `feature` is the web-features id (https://web-platform-dx.github.io/web-features-explorer/),
+ * `files` the Luma sources allowed to use it (relative to the Luma root), `why`
+ * the test and what happens without the feature. Anything else, anywhere, fails.
+ */
+export const ALLOW = [
+  {
+    // Baseline Newly available 2025-01-27 (Safari on iOS 18.3): Widely about 2027-07.
+    feature: 'popover',
+    files: ['src/widgets/autocomplete/index.ts', 'src/widgets/recommender/index.ts', 'src/widgets/search/in-place.ts'],
+    why:
+      "src/main.ts loads the autocomplete, and sets up the popup recommender, only when HTMLElement.prototype has showPopover: without it the site keeps its own suggestions and no popup opens. In-place search closes a host's [popover] around the form only where the API exists (without it `:popover-open` is an invalid selector).",
+  },
+  {
+    // Baseline Newly available 2026-01-13. Read through `any` (not in this TS lib), so the rule cannot see it: listed for the record.
+    feature: 'navigation',
+    files: ['src/core/sense.ts'],
+    why: 'URL changes come from navigation.currententrychange when window.navigation exists, else from a wrapped pushState/replaceState and popstate.',
+  },
+  {
+    // Limited availability (Chromium). navigator.connection through `any`, as above (seen in a build's output).
+    feature: 'network-information',
+    files: ['src/widgets/search/speculate.ts'],
+    why: 'Results are not fetched ahead while typing on a Save-Data or 2G connection when navigator.connection says so; without it (Firefox, Safari) they are (offline aside).',
+  },
+  {
+    // Limited availability (Chromium only). document.prerendering through `any`, as above.
+    feature: 'speculation-rules',
+    files: ['src/core/speculation.ts', 'src/core/takeover.ts', 'src/main.ts'],
+    why: "The prerender rule is added only when HTMLScriptElement.supports('speculationrules'); document.prerendering is undefined (falsy) elsewhere, so a hold's timer starts at once.",
+  },
+];
+
+const JS =/\.(?:[cm]?js|ts)$/;
+const CSS = /\.css$/;
+const SKIP = /(?:^|\/)(?:node_modules|dist|\.cache)(?:\/|$)|\.d\.ts$|\.min\.js$/;
+
+const need = async (name) => {
+  try {
+    return await import(name);
+  } catch (e) {
+    if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
+    console.error(`baseline: ${name} is not installed: \`yarn install\`.`);
+    process.exit(2);
+  }
+};
+
+/** Per file: the features of ALLOW it may use (paths relative to the Luma root). */
+const allowedIn = (file) => ALLOW.filter((a) => a.files.some((f) => resolve(LUMA, f) === file)).map((a) => a.feature);
+
+/**
+ * ESLint flat config: the Baseline rule on JS and TS (type-aware in TS: the
+ * nearest tsconfig.json). `built`: the files are a build's output (Luma and
+ * its dependencies bundled together), where every ALLOW feature passes.
+ */
+export const eslintConfig = async (cwd, files, built = false) => {
+  const { default: baselineJs } = await need('eslint-plugin-baseline-js');
+  const tsParser = await need('@typescript-eslint/parser');
+  const rule = (ignoreFeatures = []) => [
+    'error',
+    { available: 'widely', includeWebApis: { preset: 'type-aware' }, includeJsBuiltins: { preset: 'type-aware' }, ...(ignoreFeatures.length ? { ignoreFeatures } : {}) },
+  ];
+  if (built) return [{ files: ['**/*.{js,mjs}'], plugins: { 'baseline-js': baselineJs }, languageOptions: { ecmaVersion: 'latest', sourceType: 'module' }, rules: { 'baseline-js/use-baseline': rule(ALLOW.map((a) => a.feature)) } }];
+  const perFile = files.map((f) => [f, allowedIn(f)]).filter(([, a]) => a.length);
+  return [
+    { linterOptions: { reportUnusedDisableDirectives: 'error' } },
+    { files: ['**/*.{js,mjs,cjs,ts}'], plugins: { 'baseline-js': baselineJs }, languageOptions: { ecmaVersion: 'latest', sourceType: 'module' }, rules: { 'baseline-js/use-baseline': rule() } },
+    { files: ['**/*.ts'], languageOptions: { parser: tsParser, parserOptions: { projectService: true, tsconfigRootDir: cwd } } },
+    // Luma's inline early-hold snippet is a classic script (ES5); everything else is a module.
+    { files: ['snippet/*.js'], languageOptions: { sourceType: 'script' } },
+    ...perFile.map(([f, allowed]) => ({ files: [relative(cwd, f)], rules: { 'baseline-js/use-baseline': rule(allowed) } })),
+  ];
+};
+
+/** Stylelint config: the Baseline rule only (no style rules). */
+export const stylelintConfig = () => ({
+  plugins: ['stylelint-plugin-use-baseline'],
+  rules: { 'plugin/use-baseline': [true, { available: 'widely' }] },
+  reportNeedlessDisables: true,
+  reportInvalidScopeDisables: true,
+});
+
+/** Lint a CSS string (CSS that Luma builds in TS): the warnings' texts. */
+export const lintCss = async (code, name = 'inline.css') => {
+  const { default: stylelint } = await need('stylelint');
+  const r = await stylelint.lint({ code, codeFilename: name, config: stylelintConfig(), configBasedir: LUMA });
+  return r.results.flatMap((x) => x.warnings.map((w) => `${w.line}:${w.column} ${w.text}`));
+};
+
+const walk = (root, p = root, out = []) => {
+  if (SKIP.test(relative(root, p))) return out;
+  if (statSync(p).isDirectory()) for (const e of readdirSync(p)) walk(root, resolve(p, e), out);
+  else out.push(p);
+  return out;
+};
+
+/**
+ * Lint `paths` (files or folders, relative to `cwd`): prints the problems,
+ * resolves to their count. `built`: `paths` are a build's output (`dist/`):
+ * its scripts, dependencies included, with the ALLOW features passing anywhere.
+ */
+export const check = async (paths, { cwd = process.cwd(), built = false } = {}) => {
+  const all = [];
+  for (const p of paths) {
+    const abs = resolve(cwd, p);
+    if (!existsSync(abs)) throw new Error(`baseline: ${p} does not exist`);
+    walk(abs, abs, all);
+  }
+  const js = all.filter((f) => (built ? /\.m?js$/ : JS).test(f));
+  const css = built ? [] : all.filter((f) => CSS.test(f));
+  let problems = 0;
+
+  const { ESLint } = await need('eslint');
+  const eslint = new ESLint({ cwd, overrideConfigFile: true, overrideConfig: await eslintConfig(cwd, js, built), errorOnUnmatchedPattern: false, ignore: false });
+  const results = js.length ? await eslint.lintFiles(js) : [];
+  problems += results.reduce((n, r) => n + r.errorCount + r.warningCount, 0);
+  const out = (await eslint.loadFormatter('stylish')).format(results);
+  if (out) console.log(out);
+
+  if (css.length) {
+    const { default: stylelint } = await need('stylelint');
+    const r = await stylelint.lint({ files: css, config: stylelintConfig(), configBasedir: LUMA, formatter: 'string', cwd });
+    const n = r.results.reduce((k, x) => k + x.warnings.length + (x.parseErrors?.length ?? 0), 0);
+    problems += n;
+    if (n) console.log(r.report);
+  }
+  console.log(`baseline: ${js.length} scripts, ${css.length} stylesheets${built ? ' (built)' : ''}, ${problems ? `${problems} problem(s): newer than Baseline Widely available (README.md, "Browser support")` : 'all Baseline Widely available'}`);
+  return problems;
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const args = process.argv.slice(2);
+  const built = args.includes('--built');
+  const paths = args.filter((a) => a !== '--built');
+  if (!paths.length) {
+    console.error('usage: node build/baseline.mjs [--built] <file or folder>...');
+    process.exit(2);
+  }
+  process.exit((await check(paths, { built })) ? 1 : 0);
+}

package/build/tooling.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// An integration's setup for Luma's tools (`yarn luma <tool>`, bin/luma.mjs):
+// one script in its package.json, and its storefront's host in its
+// luma.config.mjs (bin/config.mjs). A tool Luma adds then needs nothing in the
+// integration. Run from the integration repository:
+//
+//   yarn luma tooling                          what is missing (exit 1 if anything)
+//   yarn luma tooling --write                  add it (the host from a script that sets LBX_HOST)
+//   yarn luma tooling --write --host www.shop.example
+//   node luma/build/tooling.mjs --write        the same before the luma script exists
+//
+// Scripts already there are never changed: per-tool ones (`"a11y": "LBX_HOST=… node luma/a11y/run.mjs"`)
+// keep working, `yarn luma a11y` is the same without them.
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILE, OLD_CONFIG_FILE } from '../bin/config.mjs';
+
+/** The one script an integration needs for every tool: the package's `luma` command, or the luma/ submodule's script. */
+export const LUMA_SCRIPT = fileURLToPath(import.meta.url).includes('/node_modules/') ? 'luma' : 'node luma/bin/luma.mjs';
+
+/** The storefront host a script of the package sets (LBX_HOST=…, the older per-tool scripts), or ''. */
+export const hostOf = (pkg) => {
+  for (const s of Object.values(pkg.scripts ?? {})) {
+    const m = /\bLBX_HOST=([^\s;&]+)/.exec(String(s));
+    if (m && !m[1].includes('<')) return m[1];
+  }
+  return '';
+};
+
+/** The host luma.config.mjs exports (`export const host = '…'`), read from its source, or ''. */
+export const configHost = (source) => /^\s*export\s+const\s+host\s*=\s*['"]([^'"]+)['"]/m.exec(source ?? '')?.[1] ?? '';
+
+/** What is missing: the luma script, the storefront's host in luma.config.mjs. */
+export const missing = (pkg, configSource) => [...(pkg.scripts?.luma ? [] : ['luma']), ...(configHost(configSource) ? [] : ['host'])];
+
+/** The package with the luma script (left as it is when there), and luma.config.mjs with the host (created when absent). */
+export const withTooling = (pkg, configSource, { host = configHost(configSource) || hostOf(pkg) } = {}) => {
+  const gone = missing(pkg, configSource);
+  if (gone.includes('host') && !host) throw new Error("the storefront's host is not known: pass --host <name> (it goes into luma.config.mjs)");
+  const scripts = { ...(pkg.scripts ?? {}) };
+  scripts.luma ??= LUMA_SCRIPT;
+  const line = `// The storefront's host name: Luma's tools (yarn luma <tool>) open it, LBX_HOST overrides it.\nexport const host = '${host}';\n`;
+  // After the file's opening comment (what it is), before its code.
+  const head = /^(?:[ \t]*\/\/[^\n]*\n)*/.exec(configSource ?? '')?.[0] ?? '';
+  const config = !gone.includes('host') ? configSource : configSource ? `${head}${head ? '\n' : ''}${line}\n${configSource.slice(head.length).replace(/^\n+/, '')}` : `// This integration's settings for Luma's tools (Luma's README, yarn luma <tool>).\n${line}`;
+  return { pkg: { ...pkg, scripts }, config };
+};
+
+// Run, not imported: through a symlink too (luma/ linked, npm's node_modules/.bin/luma)
+if (process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  const args = process.argv.slice(2);
+  const write = args.includes('--write');
+  const hi = args.indexOf('--host');
+  const host = hi >= 0 ? args[hi + 1] : undefined;
+  const dir = resolve(process.env.LBX_SITE_DIR || process.cwd());
+  const pkgFile = join(dir, 'package.json');
+  const configFile = join(dir, CONFIG_FILE);
+  // Its name before 2026-10-12 (bin/config.mjs): moved, as it is
+  const oldFile = join(dir, OLD_CONFIG_FILE);
+  const rename = !existsSync(configFile) && existsSync(oldFile);
+  if (!existsSync(pkgFile) || !existsSync(join(dir, 'integration'))) {
+    console.error(`${dir} is not an integration repository (a package.json and integration/): run it from one`);
+    process.exit(2);
+  }
+  const text = readFileSync(pkgFile, 'utf8');
+  const pkg = JSON.parse(text);
+  const configSource = existsSync(configFile) ? readFileSync(configFile, 'utf8') : rename ? readFileSync(oldFile, 'utf8') : '';
+  const gone = [...(rename ? ['rename'] : []), ...missing(pkg, configSource)];
+  const perTool = Object.entries(pkg.scripts ?? {}).filter(([, v]) => /node luma\/(a11y|parity|footprint|tasks)\/run\.mjs|yarn perf\b/.test(String(v))).map(([k]) => k);
+  if (!gone.length) {
+    console.log(`ready: yarn luma <tool> (yarn luma: the tools), the storefront ${configHost(configSource)}`);
+    if (perTool.length) console.log(`(scripts ${perTool.join(', ')} do what yarn luma <tool> does: they can go)`);
+    process.exit(0);
+  }
+  if (!write) {
+    if (rename) console.log(`missing: ${CONFIG_FILE} (the settings are in ${OLD_CONFIG_FILE}, its older name)`);
+    if (gone.includes('luma')) console.log(`missing: the "luma" script (${LUMA_SCRIPT}) in package.json`);
+    if (gone.includes('host')) console.log(`missing: the storefront's host in ${CONFIG_FILE} (export const host = '…')`);
+    console.log('yarn luma tooling --write adds them (--host <name> if no script sets LBX_HOST)');
+    process.exit(1);
+  }
+  let next;
+  try {
+    next = withTooling(pkg, configSource, host ? { host } : {});
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+  if (gone.includes('luma')) {
+    const indent = /^(\s+)"/m.exec(text)?.[1] ?? '  ';
+    writeFileSync(pkgFile, `${JSON.stringify(next.pkg, null, indent)}\n`);
+  }
+  if (rename) {
+    renameSync(oldFile, configFile);
+    const edge = dirname(oldFile);
+    if (!readdirSync(edge).length) rmdirSync(edge);
+  }
+  if (gone.includes('host')) writeFileSync(configFile, next.config);
+  const what = { rename: `${OLD_CONFIG_FILE} moved to ${CONFIG_FILE}`, luma: 'the luma script (package.json)', host: `the host ${configHost(next.config)} (${CONFIG_FILE})` };
+  console.log(`done: ${gone.map((g) => what[g]).join(', ')}`);
+}