@tollwyn/baukasten 0.0.2 → 1.2.2

package/README.md

@@ -1,3 +1,256 @@
 # @tollwyn/baukasten
 
-Placeholder. Use a 1.x version of @tollwyn/baukasten.
+What every product built on this kit shares, finished and tested: accounts with sessions and API
+keys, limits, mail, payment through Stripe, the sales numbers, the legal pages, health, log and
+server, the database with its migrations, the frame of the pages, and the tools to test a product.
+A product builds its core and nothing of this.
+
+## Set up a product
+
+A product is a SvelteKit 2 app with `@sveltejs/adapter-node` 5 and Svelte 5, tested with Playwright.
+
+```sh
+npm install --save-exact @tollwyn/baukasten@<version>
+npm install --save-dev @sveltejs/adapter-node@5 @playwright/test smtp-server
+npx --no-install baukasten-stubs
+# fill in what the product owns (below)
+npx --no-install baukasten-check
+```
+
+`baukasten-stubs` writes the files that only pass on to the package: the pages of the baukasten
+under `src/routes` (sign-up, login, account, password, email, legal pages), the root layout and the
+error page, `src/app.html`, `src/hooks.server.ts`, `server.js`, and `e2e/baukasten.spec.ts`. Never
+change them: `baukasten-check` holds them byte for byte, and a new version brings its own. Where
+they are missing, it also writes the files the product owns, as a starting point, and never over
+them: `baukasten.config.ts`, `src/app.css`, `src/lib/server/baukasten.ts` and
+`src/lib/server/handle.ts`.
+
+## What the product owns
+
+- `baukasten.config.ts`: its language (`en` or `de`), the schema of its own variables, its
+  navigation, where an account lands and the prefix of its keys, the texts of the sign-up page, its
+  catalog for Stripe, and its statements for the legal pages, which must be true. Nothing in it may
+  stay empty: the product does not build until it is filled in.
+- `src/app.css`: its own styles and colours (the variables `--bk-*` of the baukasten), which the root
+  layout loads after the base styles, so that they reach the pages of the baukasten too. See
+  «Design» below.
+- `static/`: its logo, icon and picture for shared links, named under `brand` in
+  `baukasten.config.ts`.
+- `src/lib/server/baukasten.ts`: the hooks the baukasten calls (`Hooks` of `/server`): its checks for
+  `/health/deep`, start and stop of its runs (`periodic`), deleting its data of an account, plans
+  from a subscription, a paid purchase, its own sales numbers.
+- `src/lib/server/handle.ts`: its own handle, after the baukasten's.
+- Its own pages. Their links to other pages go through `useLink` of `/ui`, else the referral tag
+  `?via=` is lost on the way to the sign-up.
+- `vite.config.ts`, passing the options of the baukasten to SvelteKit:
+  `sveltekit({ ...SVELTEKIT_OPTIONS, adapter: adapter() })`, with `SVELTEKIT_OPTIONS` from
+  `@tollwyn/baukasten`. No page is prerendered.
+- `migrations/`: its tables in the schema `public`, plain SQL, forward-only and expanding (the
+  previous version must run against the new schema). Every table that holds data of an account
+  points at it with `REFERENCES baukasten.accounts (id) ON DELETE CASCADE`. It reads the tables of
+  the baukasten only through its functions and never changes them.
+- `.env.example`, naming every variable without a value (`envExampleProblems` of `/testing`).
+- `playwright.config.ts` with `testDir: 'e2e'` and `TEST_DATABASE_URL`, a Postgres server on which the
+  tests create their databases. It sets the variables the configuration of the product requires in
+  `process.env`: the connection test starts the product with them.
+- The image: `npm run build`, then `baukasten.config.ts` and `migrations/` in its root beside
+  `build/`, `server.js` and the production `node_modules`; it starts with `CMD ["node", "server.js"]`.
+- `deploy/auslieferung.json`: version 2, `art: webapp`, the migration
+  `["node", "node_modules/@tollwyn/baukasten/dist/bin/migrate.js"]`, and under `stripe` a
+  webhook `endpunkt` at `WEBHOOK_PATH` with the events `WEBHOOK_EVENTS`, and at least the rights
+  `KEY_RIGHTS` (all three from `/server`).
+
+## Design
+
+A product brings its own design; the frame and the pages of the baukasten take it on and give way to
+it. `muster/` shows all of it with Tailwind CSS 4, Skeleton and a font from fontsource.
+
+- **Layers.** The base styles lie in two cascade layers and fix their order first:
+  `@layer bk-root, properties, theme, base, bk, components, utilities`. `bk-root`, below everything,
+  holds the variables, the page and its links; `bk`, above Tailwind's preflight and below its
+  components and utilities, holds the frame and the pages of the baukasten. Element styles of the
+  baukasten apply only inside its own pages (`.bk-ui`), the head, the notice, the foot and every
+  `Form`; the product's own pages get none of them. Any CSS of the product wins: unlayered, a
+  component or a utility. Style the frame through its classes (`.bk-head`, `.bk-name`, `.bk-nav`,
+  `.bk-main`, `.bk-foot`), as a component. Element styles meant for the product's own pages, like a
+  reset, belong in `@layer base`: unlayered, they reach the pages of the baukasten too.
+- **Colours and font.** Point the variables at the product's theme in `src/app.css`, light and dark:
+  `--bk-text`, `--bk-muted`, `--bk-background`, `--bk-surface`, `--bk-border`, `--bk-accent`,
+  `--bk-accent-text`, `--bk-error`, `--bk-success`, `--bk-radius`, `--bk-font`. With Skeleton its
+  paired tokens do both schemes at once, like `--bk-text: var(--color-surface-950-50)`, and it sets
+  `color-scheme` to the scheme of the visitor. Without Skeleton the base styles are light; a product
+  that follows a dark scheme sets `color-scheme: light dark` itself, with its dark values.
+- **Marks.** Under `brand` in `baukasten.config.ts`: `logo` (sign and name as one SVG, with its size;
+  the head shows it with the name as its text, so it must read on the head in either scheme),
+  `icon` (SVG or PNG), `image` (a PNG of 1200 × 630 pixels for shared links, named on every page at
+  the whole address of `PUBLIC_ORIGIN`) and optionally `theme`, which goes on `<html data-theme>`
+  before the first paint. The files lie in `static/`. The connection test checks that they load, of
+  their kind and size.
+- **Fonts and pictures** come from the product's own address: fontsource packages imported in
+  `src/app.css`, which Vite bundles (a small font inlined as `data:`, which the policy allows), and
+  pictures in `static/` or the product's code. Nothing from another server: the policy refuses it.
+
+## The check and the connection test
+
+`baukasten-check` runs in the root of the product, before its gate, against the installed version:
+the stubs are there and unchanged, `deploy/auslieferung.json` names the webhook and the rights of
+the baukasten, SvelteKit and Svelte fit its peer ranges and adapter-node is version 5, `overrides`
+in `package.json` replaces nothing the baukasten depends on, no migration of the product names the
+schema `baukasten` beyond its references to `baukasten.accounts`, and the configuration and
+`SVELTEKIT_OPTIONS` are in place. Exit 0 when the product fits; else exit 1 with one line per
+problem.
+
+`e2e/baukasten.spec.ts` runs the connection test in the gate of the product, against the built
+product with the doubles of Stripe and mail: sign-up with a referral tag, mail and confirmation,
+login and a new password, an API key, Checkout and the customer portal, `/vertrieb/zahlen`, the
+legal pages with the operator, the security headers, the session as the only cookie, and deleting
+the account. Playwright places its tests in the package, so a file filter misses them; run it alone
+with `npx playwright test -g "the connection of the baukasten"`.
+
+# A Shopify app
+
+A Shopify app built on this kit is a public app in the Shopify App Store, embedded in the admin of
+each store that installs it. Shopify installs it (managed installation) and bills it (Shopify App
+Pricing); the merchant never signs up or pays anywhere else. It is a SvelteKit 2 app with
+`@sveltejs/adapter-node` 5 and Svelte 5, tested with Playwright, like a web app, and on the same
+server; the accounts, Stripe and the legal pages of a web app are not part of it.
+
+What the baukasten brings for it: the installation with the token exchange and expiring offline
+tokens, refreshed under a lock per store and kept sealed; the check of the ID token of App Bridge on
+every request; the frame of the admin (content security policy per store, App Bridge and Polaris from
+the CDN of Shopify); the webhooks about privacy and the end of an installation, and the signature of
+every webhook; the plan of a store through the Partner API, and the way to Shopify's plan page;
+the Admin API of a store for the app's own queries; health, log and server, the database with its
+migrations and the work mark of runs; mail; the numbers for sales; the privacy text with the
+processing on behalf of the merchant; and the tools to test the app, the double of Shopify and the
+connection test among them.
+
+## Set up a Shopify app
+
+```sh
+npm install --save-exact @tollwyn/baukasten@<version>
+npm install --save-dev @sveltejs/adapter-node@5 @playwright/test smtp-server
+npx --no-install baukasten-stubs shopify
+# fill in what the app owns (below)
+npx --no-install baukasten-check
+```
+
+`baukasten-stubs shopify` writes the files that only pass on to the package: `server.js`,
+`src/app.html` (App Bridge first, then Polaris, from the CDN of Shopify; the client ID filled in by the
+server), `src/hooks.server.ts`, and `e2e/baukasten.spec.ts`. Never change them. Where they are
+missing, it writes the files the app owns as a starting point: `baukasten.config.ts`,
+`shopify.app.toml`, `src/lib/server/baukasten.ts` and `src/lib/server/handle.ts`.
+
+## What the Shopify app owns
+
+- `baukasten.config.ts`, with `defineShopifyApp` of `@tollwyn/baukasten`: its language (`en`
+  or `de`, for the privacy text and the few pages of the baukasten; its own pages may speak the
+  language of its market), the schema of its own variables, its plans with the handles they have in
+  the Partner Dashboard and whether each costs money, and its statements for the privacy text,
+  which must be true: what it does (`service`), the personal data it processes for the merchant
+  (`data`), and who else gets them (`recipients`).
+- `shopify.app.toml`, the configuration of the app at Shopify, deployed with the Shopify CLI.
+  `baukasten-check` holds: `application_url` is `https://<subdomain>.tollwyn.com` with the
+  `subdomain` of `deploy/auslieferung.json`, `auth.redirect_urls` is exactly
+  `["https://<subdomain>.tollwyn.com/shopify/auth"]`, `embedded = true`, no
+  `use_legacy_install_flow`, `webhooks.api_version` is `SHOPIFY_API_VERSION` of `/shopify`, every
+  subscription goes to `/shopify/webhooks` (`SHOPIFY_WEBHOOK_PATH`), and they name
+  `app/uninstalled` and the three compliance topics. The app's own topics go to the same path. Its
+  scopes are only what its core needs (`read_all_orders` only with a reason). `client_id` stays empty
+  until the app is linked. No app proxy, events or customer accounts, whose requests would reach the
+  app unchecked, and no extensions, whose commands the Shopify CLI would run when it deploys the
+  app.
+- `src/lib/server/baukasten.ts`: the kit, `shopifyBaukasten(app, hooks)` of `/shopify`, with the
+  hooks it calls (`ShopifyHooks`): checks for `/health/deep`, start and stop of runs (`periodic`),
+  `webhook` for the app's own topics, and, if the app keeps personal data for the merchant (`data` is
+  not empty, and then they are required), `customerData` (what it keeps of a customer, as text,
+  which the baukasten mails to the store) and `redactCustomer` (deletes it). The baukasten answers
+  a webhook at once and applies it after, in a run of its own: each hook runs in the transaction of
+  its webhook, once; a failure rolls it back, the webhook is tried again later, for about a day, and
+  after the last try it gives up with an error in the log.
+- Its pages, with the web components of Polaris (`<s-page>`, `<s-section>`, …). In a `load` or
+  action, `kit.shop(event)` gives the store of the request (`domain`) and its plan (`plan.handle`);
+  every page is opened by a store with a plan, so the app gates its features by the handle. A store
+  without a plan the baukasten leads to the plan page of Shopify, which also changes a plan:
+  `https://admin.shopify.com/store/<store>/charges/<app handle>/pricing_plans`, opened with
+  `window.open(url, '_top')`. Forms post with `use:enhance`: App Bridge adds the ID token to every
+  request of the page to the app, and a request without it gets no answer of the app.
+- The Admin API: `kit.admin(domain).graphql(query, variables)` gives the data unparsed; the app
+  parses them with Zod. Over the store's limit it waits and tries again a few times, then fails. It
+  throws `ShopGone` when the store gave no token that works (removed, or only the merchant can give
+  a new one by opening the app), and `AdminRefused` for errors of the query. Only GraphQL, in
+  `SHOPIFY_API_VERSION`.
+- Runs: `periodic` with the work mark, as in a web app; a run asks the Admin API of a store with
+  `kit.admin(domain)` and skips a store that is gone.
+- `vite.config.ts`: `sveltekit({ ...SHOPIFY_SVELTEKIT_OPTIONS, adapter: adapter() })`, with
+  `SHOPIFY_SVELTEKIT_OPTIONS` from `@tollwyn/baukasten`. No page is prerendered.
+- `migrations/`: its tables in the schema `public`, forward-only and expanding. Every table that
+  holds data of a store points at it with `REFERENCES baukasten.shops (domain) ON DELETE CASCADE`:
+  so `shop/redact` deletes them with the store.
+- `.env.example` (`envExampleProblems` of `/testing`) and `playwright.config.ts`, as in a web app.
+- The image: as a web app's, with `shopify.app.toml` in its root as well.
+- `deploy/auslieferung.json`: version 2, `art: shopify`, `name`, `subdomain` (without `shopify` or
+  `example`, which the review refuses in an address), the migration
+  `["node", "node_modules/@tollwyn/baukasten/dist/bin/migrate.js", "shopify"]`, its own
+  `variablen`, and no `stripe`.
+
+## Testing a Shopify app
+
+`createTestDatabase({ art: 'shopify' })` migrates the layer of a Shopify app. `startShopify({ scopes })`
+of `/testing` is a double of Shopify, which grants the tokens the scopes of the app's
+`shopify.app.toml`: `env()` gives the variables that send the app to it, with a client
+ID of its own (`SHOPIFY_API_BASE`, `SHOPIFY_CLIENT_ID`, tests only); `addShop` makes a store,
+`idToken` mints the ID token App Bridge would give, `subscribe` chooses a plan, `uninstall` removes
+the app, `answerAdmin` answers the app's own queries of the Admin API, and `webhook` sends a signed
+webhook. A page of the admin is `/?embedded=1&shop=<store>&host=…&id_token=<ID token>`; a request of
+a page carries `authorization: Bearer <ID token>`.
+
+`e2e/baukasten.spec.ts` runs the connection test of a Shopify app: health, the page outside the
+admin, the bounce page, the installation and the way to the plans, the frame and the headers, the ID
+token as a bearer token, the webhooks with and without signature, the numbers for sales, the end of
+an installation and `shop/redact`, the privacy text, and the log. A webhook is applied after its
+answer, so a test waits for its effect (`expect.poll`).
+
+## The Shopify sample against a store
+
+`muster-shopify/` runs against the double in the gate. Against a development store it runs from a
+copy outside the repo: there `shopify.app.toml` has `automatically_update_urls_on_dev = true` and
+the client ID the Shopify CLI gives it when it creates the app, a `shopify.web.toml` whose `dev`
+command starts the built sample with `PUBLIC_ORIGIN` from the address of the tunnel and
+`SHOPIFY_API_SECRET` from the CLI, and `shopify app dev` installs it in the store. The app needs
+Shopify App Pricing with the plans `basic` and `free` in the Partner Dashboard, and the variables of
+the Partner API (a token that may manage apps, and the number of the organization).
+
+## Linking and deploying the app
+
+The client ID comes into `shopify.app.toml` when the app is created in the Dev Dashboard and linked.
+Linking rewrites the file with the defaults of a new app: only its `client_id` is kept, the rest
+comes back from git, and `baukasten-check` passes again before anything is deployed. The Partner
+Dashboard gets the distribution «Public», the fields of protected customer data with their reasons,
+and Shopify App Pricing with the plans under the handles of `baukasten.config.ts`, all as the build
+report names them; `shopify app deploy` publishes the configuration. The privacy text is at
+`<origin>/privacy`, for the listing.
+
+The questions of «Data protection details» in the Partner Dashboard, answered by what the fleet and
+the baukasten do:
+
+- Minimum data, purpose, retention: the app asks only the scopes and fields its core needs (the
+  build report names each with its reason); it processes them only for its `service`; a store's data are
+  deleted at `shop/redact`, 48 hours after the app is removed, a customer's at `customers/redact`,
+  and backups end after about 30 days.
+- Merchants informed, agreement with merchants: the privacy text at `<origin>/privacy` says what the
+  app processes and holds the clauses of processing on behalf of the merchant (Art. 28 GDPR), which
+  the merchant accepts by installing the app.
+- Consent, opt-outs, automated decisions: the app uses no data for marketing, sells none, and makes no
+  automated decisions with legal effect.
+- Encryption: every connection is TLS; the database of the app (Neon) is encrypted at rest; the
+  tokens of the stores are sealed with AES-256-GCM; every backup is encrypted (age) before it leaves
+  the server.
+- Test and production data: kept apart. Tests run with the double of Shopify and their own databases,
+  never with data of a store.
+- Access: the database of the app is reached only by the app and, for its encrypted backups, by the
+  delivery service; one operator, no other staff. The application logs every request with the store
+  it served.
+- Loss and incidents: on a breach the operator stops the app through the delivery service, finds what
+  was reached from the logs, and tells the stores concerned by email without undue delay, as the
+  privacy text promises.

package/dist/bin/check.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/check.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { productProblems } from '../check.js';
+const MANIFEST = z.object({
+    name: z.string(),
+    version: z.string(),
+    dependencies: z.record(z.string(), z.string()),
+    peerDependencies: z.record(z.string(), z.string())
+});
+/** The package.json of this very installation: dist/bin/ lies two folders below it. */
+const baukasten = MANIFEST.parse(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')));
+const root = process.cwd();
+/** What is not there is undefined; any other failure to read is one of the check. */
+function unlessMissing(read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, 'code') === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+const files = {
+    read: (file) => unlessMissing(() => readFileSync(path.join(root, file), 'utf8')),
+    names: (folder) => unlessMissing(() => readdirSync(path.join(root, folder))) ?? []
+};
+const problems = productProblems(files, baukasten);
+if (problems.length > 0) {
+    for (const problem of problems)
+        process.stderr.write(`${problem}\n`);
+    process.exitCode = 1;
+}
+else {
+    process.stdout.write(`the product fits ${baukasten.name} ${baukasten.version}\n`);
+}

package/dist/bin/migrate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/migrate.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// One JSON line says what the command did; the exit code is the verdict. A database that a newer
+// version migrated further is fine, with a warning: the delivery service falls back to this version
+// when the newer one starts unhealthy.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isProduct } from '../product.js';
+import { createDb } from '../server/adapter/db.js';
+import { exitAfterLog, log } from '../server/adapter/log.js';
+import { migrate, migrationSources } from '../server/adapter/migrate.js';
+import { createStripe } from '../server/adapter/stripe.js';
+import { foreignWebhooks, setUpCatalog } from '../server/catalog.js';
+import { ConfigError, databaseUrlOf, loadConfig } from '../server/config.js';
+import { testData } from '../server/test-accounts.js';
+import { isShopifyApp } from '../shopify/app.js';
+import { loadShopifyConfig } from '../shopify/config.js';
+import { APP_TOML } from '../shopify/toml.js';
+const TEST_ACCOUNTS = 'node node_modules/@tollwyn/baukasten/dist/bin/test-accounts.js';
+async function configurationIn(root) {
+    const loaded = await import(pathToFileURL(path.join(root, 'baukasten.config.ts')).href);
+    return typeof loaded === 'object' && loaded !== null ? Reflect.get(loaded, 'default') : undefined;
+}
+function configured(product) {
+    if (!isProduct(product)) {
+        throw new ConfigError([
+            'baukasten.config.ts does not export the product of defineProduct as its default'
+        ]);
+    }
+    return { product, config: loadConfig(process.env, product) };
+}
+async function webapp(root, databaseUrl) {
+    const withStripe = process.env.NODE_ENV === 'production' || (process.env.STRIPE_SECRET_KEY ?? '').trim() !== '';
+    // Read before anything changes: a configuration that does not hold migrates nothing.
+    const setup = withStripe ? configured(await configurationIn(root)) : null;
+    const { applied, ahead } = await migrate(databaseUrl, migrationSources(root, 'webapp'));
+    warnAhead(ahead);
+    const stripe = setup === null
+        ? 'skipped: no STRIPE_SECRET_KEY'
+        : await stripeOf(setup.config, setup.product, databaseUrl);
+    log.info('migrate: done', { applied, stripe });
+}
+/** Migrates a Shopify app, whose configuration holds in production before anything changes. */
+async function shopify(root, databaseUrl) {
+    if (process.env.NODE_ENV === 'production') {
+        const app = await configurationIn(root);
+        if (!isShopifyApp(app)) {
+            throw new ConfigError([
+                'baukasten.config.ts does not export the app of defineShopifyApp as its default'
+            ]);
+        }
+        const toml = path.join(root, APP_TOML);
+        loadShopifyConfig(process.env, app, existsSync(toml) ? readFileSync(toml, 'utf8') : undefined);
+    }
+    const { applied, ahead } = await migrate(databaseUrl, migrationSources(root, 'shopify'));
+    warnAhead(ahead);
+    log.info('migrate: done', { applied });
+}
+function warnAhead(ahead) {
+    if (ahead.baukasten.length > 0 || ahead.product.length > 0) {
+        log.warn('migrate: the database is ahead of this version', { ahead });
+    }
+}
+async function stripeOf(config, product, databaseUrl) {
+    if (config.stripe.kind === 'none')
+        return 'skipped: no STRIPE_SECRET_KEY';
+    const stripe = createStripe(config.stripe);
+    const shop = { name: config.name, origin: config.publicOrigin };
+    const steps = await setUpCatalog(stripe, product.catalog, shop);
+    const foreign = await foreignWebhooks(stripe, shop.origin);
+    if (foreign.length > 0) {
+        log.warn('migrate: webhook endpoints of another product in the Stripe account', {
+            endpoints: foreign
+        });
+    }
+    if (config.stripe.mode === 'live') {
+        const db = createDb(databaseUrl, log);
+        try {
+            const data = await testData(db);
+            // Counted, without addresses: the command lists them for whoever decides.
+            if (data.accounts > 0) {
+                log.warn('migrate: accounts from the test mode remain', {
+                    ...data,
+                    command: TEST_ACCOUNTS
+                });
+            }
+        }
+        finally {
+            await db.close();
+        }
+    }
+    return steps;
+}
+try {
+    const root = process.cwd();
+    const databaseUrl = databaseUrlOf(process.env);
+    const art = process.argv.slice(2);
+    if (art.length === 0)
+        await webapp(root, databaseUrl);
+    else if (art.length === 1 && art[0] === 'shopify')
+        await shopify(root, databaseUrl);
+    else
+        throw new ConfigError([`the migration command takes shopify or nothing, not ${art.join(' ')}`]);
+}
+catch (error) {
+    if (error instanceof ConfigError)
+        log.error('migrate: not started', { problems: error.problems });
+    else
+        log.error('migrate: failed', { error });
+    await exitAfterLog(1);
+}

package/dist/bin/stubs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/stubs.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { SHOPIFY_STARTING_POINTS, SHOPIFY_STUBS, STARTING_POINTS, STUBS } from '../stubs.js';
+function write(root, file, content, note) {
+    const target = path.join(root, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, content);
+    process.stdout.write(`wrote ${file}${note}\n`);
+}
+const root = process.cwd();
+const art = process.argv.slice(2);
+const files = art.length === 0
+    ? { stubs: STUBS, starting: STARTING_POINTS }
+    : art.length === 1 && art[0] === 'shopify'
+        ? { stubs: SHOPIFY_STUBS, starting: SHOPIFY_STARTING_POINTS }
+        : null;
+if (files === null) {
+    process.stderr.write(`baukasten-stubs: it takes shopify or nothing, not ${art.join(' ')}\n`);
+    process.exitCode = 1;
+}
+else if (!existsSync(path.join(root, 'package.json'))) {
+    process.stderr.write('baukasten-stubs: no package.json here; run it in the root of the product\n');
+    process.exitCode = 1;
+}
+else {
+    for (const [file, content] of Object.entries(files.stubs)) {
+        const target = path.join(root, file);
+        if (!existsSync(target) || readFileSync(target, 'utf8') !== content) {
+            write(root, file, content, '');
+        }
+    }
+    for (const [file, content] of Object.entries(files.starting)) {
+        if (!existsSync(path.join(root, file))) {
+            write(root, file, content, ', a starting point: fill it in');
+        }
+    }
+}

package/dist/bin/test-accounts.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/test-accounts.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Lists or, with --delete, deletes the accounts from the test mode of Stripe once the product runs
+// with the live key, in its container and with its environment; it never touches Stripe.
+import { createDb } from '../server/adapter/db.js';
+import { log } from '../server/adapter/log.js';
+import { ConfigError, databaseUrlOf, stripeModeOf } from '../server/config.js';
+import { deleteTestAccounts, testAccounts } from '../server/test-accounts.js';
+const COMMAND = 'node node_modules/@tollwyn/baukasten/dist/bin/test-accounts.js';
+function say(line) {
+    process.stdout.write(`${line}\n`);
+}
+function refuse(reason) {
+    process.stderr.write(`test-accounts: ${reason}\n`);
+    process.exitCode = 1;
+}
+async function run(args) {
+    if (args.length > 1 || (args.length === 1 && args[0] !== '--delete')) {
+        return refuse(`usage: ${COMMAND} [--delete]`);
+    }
+    const key = (process.env.STRIPE_SECRET_KEY ?? '').trim();
+    if (key === '' || stripeModeOf(key) !== 'live') {
+        return refuse('STRIPE_SECRET_KEY is no live key: every account is from the test mode');
+    }
+    const db = createDb(databaseUrlOf(process.env), log);
+    try {
+        if (args[0] === '--delete') {
+            const deleted = await deleteTestAccounts(db);
+            say(`Deleted accounts from the test mode: ${deleted.accounts}, their invoices: ${deleted.invoices}, their purchases: ${deleted.purchases}.`);
+            return;
+        }
+        const accounts = await testAccounts(db);
+        if (accounts.length === 0)
+            return say('No accounts from the test mode.');
+        say(`Accounts from the test mode: ${accounts.length}.`);
+        for (const account of accounts) {
+            say([
+                account.id,
+                // A deleted account keeps its row without the address.
+                account.email ?? '(deleted)',
+                `created ${account.createdAt.toISOString()}`,
+                `via ${account.via}`,
+                `subscriptions ${account.subscriptions.length === 0 ? 'none' : account.subscriptions.join(', ')}`,
+                `invoices ${account.invoices}`,
+                `purchases ${account.purchases}`
+            ].join('  '));
+        }
+        say(`Delete them, and everything on them, with: ${COMMAND} --delete`);
+    }
+    finally {
+        await db.close();
+    }
+}
+try {
+    await run(process.argv.slice(2));
+}
+catch (error) {
+    refuse(error instanceof ConfigError
+        ? error.problems.join('; ')
+        : error instanceof Error
+            ? error.message
+            : String(error));
+}

package/dist/check.d.ts

@@ -0,0 +1,20 @@
+/** What the check reads of the package.json of the installed baukasten. */
+export interface InstalledBaukasten {
+    name: string;
+    version: string;
+    dependencies: Readonly<Record<string, string>>;
+    peerDependencies: Readonly<Record<string, string>>;
+}
+/** The files of the product, by their path from its root. */
+export interface ProductFiles {
+    /** A file, or undefined where there is none. */
+    read(path: string): string | undefined;
+    /** The names in a folder, as the migration reads them; none where there is no folder. */
+    names(folder: string): readonly string[];
+}
+/** The migration command of a Shopify app in its delivery manifest. */
+export declare const SHOPIFY_MIGRATION: string[];
+/** Whether `version` lies in the caret range `range` from 1.0.0 on; a pre-release lies in none. */
+export declare function fits(version: string, range: string): boolean;
+/** What keeps the product from fitting the installed baukasten; empty when it fits. */
+export declare function productProblems(files: ProductFiles, baukasten: InstalledBaukasten): string[];