@dokebi/cli 0.4.26 → 0.4.28

package/dist/deploy.js

@@ -0,0 +1,564 @@
+// `dokebi deploy init` and `dokebi deploy proxy` (D-0184): the deployment files of an existing
+// project, per instance, written into deploy/ (the repository keeps them; no secret is in any).
+import { createHash } from 'node:crypto';
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseConfig } from '@dokebi/config';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { isPlaceholder } from './config-init.js';
+import { requiredSecretPaths, schemaTypes, unreadableWarning } from './config-secrets.js';
+import { configShow } from './config-show.js';
+import { CONFIG_FILE, renderConfig } from './configuration.js';
+import { BACKUP_SCRIPT, RESTORE_DRILL_SCRIPT } from './deploy-scripts.js';
+import { backupService, backupTimer, caddyfile, composeFile, deployGuide, layout, nginxConf, systemdUnit, } from './deploy-templates.js';
+import { DEPLOYMENT_FILES } from './deployment.js';
+import { debug, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { exists, parseObject, securePath } from './filesystem.js';
+import { optionsKey } from './manifest.js';
+import { readState } from './project-state.js';
+import { applyReloadableMarks, reloadSchemas } from './reloadable.js';
+import { Transaction } from './transaction.js';
+const EXAMPLE = 'dokebi.example.yaml';
+const INSTANCE = /^[a-z][a-z0-9-]{0,23}$/;
+const DEFAULT_PORTS = { production: 3000, staging: 3001 };
+/** URL schemes whose URL is a credential on a server (it carries the user and password). */
+const CREDENTIAL_URL = /^(postgres|postgresql|mysql|mariadb|mongodb|mongodb\+srv|redis|rediss|nats|tls|smtp|smtps|amqp|amqps):/i;
+/** The marker line of a file deploy init wrote: a later run rewrites it only while unchanged. */
+function marker(path, body) {
+    const digest = createHash('sha256').update(body).digest('hex').slice(0, 16);
+    const text = `generated by dokebi deploy (${digest}); edit freely, a later run then keeps it`;
+    if (path.endsWith('.md'))
+        return `<!-- ${text} -->\n`;
+    if (path.endsWith('.mjs'))
+        return `// ${text}\n`;
+    return `# ${text}\n`;
+}
+function withMarker(path, body) {
+    return marker(path, body) + body;
+}
+/** Whether `text` is a file deploy wrote and nobody changed since. */
+function untouched(path, text) {
+    const end = text.indexOf('\n');
+    return end > 0 && text.slice(0, end + 1) === marker(path, text.slice(end + 1));
+}
+/** The app name of package.json, as unit, user and folder names take it. */
+async function appName(root) {
+    const pkg = parseObject(await readFile(join(root, 'package.json'), 'utf8'), 'package.json');
+    const raw = typeof pkg.name === 'string' ? pkg.name : '';
+    const name = raw
+        .replace(/^@[^/]+\//, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^[^a-z]+|-+$/g, '')
+        .slice(0, 24)
+        .replace(/-+$/, '');
+    if (!/^[a-z][a-z0-9-]*$/.test(name))
+        throw new CliError('APP_NAME_INVALID', 'package.json has no name the server names can be made from (letters, digits, -)', {
+            phase: 'arguments',
+            details: {
+                name: raw,
+                fix: 'set "name" in package.json to a short lowercase name, e.g. "shop"',
+            },
+        });
+    return name;
+}
+async function projectState(root) {
+    try {
+        return readState(parseObject(await readFile(await securePath(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    }
+    catch (error) {
+        if (isMissing(error))
+            throw new CliError('NOT_A_PROJECT', 'No .dokebi/state.json: run this in a Dokebi project (the folder with package.json, dokebi.yaml and .dokebi/state.json)', { phase: 'arguments', details: { root, file: '.dokebi/state.json' } });
+        throw error;
+    }
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Every `section.key…` path whose value is a URL with a credential scheme or a placeholder of one. */
+function credentialUrls(value, path, found) {
+    if (Array.isArray(value))
+        for (const [index, item] of value.entries())
+            credentialUrls(item, [...path, `${index}`], found);
+    else if (value && typeof value === 'object')
+        for (const [key, item] of Object.entries(value))
+            credentialUrls(item, [...path, key], found);
+    else if (typeof value === 'string' &&
+        path.at(-1)?.toLowerCase() === 'url' &&
+        (CREDENTIAL_URL.test(value) || (isPlaceholder(value) && path.length > 1)))
+        found.add(path.join('.'));
+}
+/** The settings of the development machine and the sample: which option paths are secrets. */
+async function secretPaths(root, sample) {
+    const found = new Set();
+    const sampleOptions = parseConfig(sample).options;
+    const shown = await configShow(root, undefined, { source: sample, file: EXAMPLE });
+    // Without a plugin's schema every text of its section would count as a secret.
+    const unreadable = (shown.warnings ?? []).filter((item) => item.code === 'OPTIONS_SCHEMA_UNREADABLE');
+    if (unreadable.length)
+        throw new CliError('OPTIONS_SCHEMA_UNREADABLE', `The options schemas of ${unreadable.map((item) => item.plugin).join(', ')} could not be read, so the secrets of the settings cannot be told apart`, {
+            phase: 'arguments',
+            details: {
+                plugins: unreadable.map((item) => item.plugin),
+                fix: 'npm install, then run the command again',
+            },
+        });
+    for (const path of shown.secrets)
+        found.add(path);
+    credentialUrls(sampleOptions, [], found);
+    const development = await readOptional(join(root, CONFIG_FILE));
+    if (development !== undefined) {
+        const options = parseConfig(development).options;
+        for (const path of (await configShow(root, undefined, { source: development, file: CONFIG_FILE })).secrets)
+            found.add(path);
+        credentialUrls(options, [], found);
+    }
+    const planned = await requiredSecretPaths(root, (development === undefined ? sampleOptions : parseConfig(development).options));
+    for (const path of planned.paths)
+        found.add(path);
+    // A secret inside a list item (logging.targets.0.token) moves the whole list: a list is one
+    // value of the secrets file (it cannot be split between two files).
+    const sources = [
+        sampleOptions,
+        development === undefined ? {} : parseConfig(development).options,
+    ];
+    const cut = (path) => {
+        const keys = path.split('.');
+        for (let end = 1; end < keys.length; end++)
+            if (sources.some((options) => Array.isArray(valueAt(options, keys.slice(0, end)))))
+                return keys.slice(0, end).join('.');
+        return path;
+    };
+    const paths = [...new Set([...found].map(cut))].sort();
+    // A path under another listed path is covered by it.
+    return {
+        paths: paths.filter((path) => !paths.some((other) => path !== other && path.startsWith(`${other}.`))),
+        unreadable: planned.unreadable,
+    };
+}
+function valueAt(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (Array.isArray(value) && /^\d+$/.test(key))
+            value = value[Number(key)];
+        else if (value && typeof value === 'object' && Object.hasOwn(value, key))
+            value = value[key];
+        else
+            return undefined;
+    }
+    return value;
+}
+/** A placeholder for a secret of the secrets sample, saying what goes there (never a value). */
+function placeholderFor(path, at, current, types) {
+    const kind = typeof current === 'string'
+        ? current.slice(0, Math.max(0, current.indexOf(':'))).toLowerCase()
+        : '';
+    if (path.endsWith('.url')) {
+        if (kind.startsWith('postgres') || (/dokebi-db/.test(path) && kind === ''))
+            return `<postgres URL: postgres://USER:PASSWORD@127.0.0.1:5432/${at.database}>`;
+        if (kind.startsWith('mongodb'))
+            return `<mongodb URL: mongodb://USER:PASSWORD@127.0.0.1:27017/${at.database}>`;
+        if (kind === 'mysql' || kind === 'mariadb')
+            return `<${kind} URL: ${kind}://USER:PASSWORD@127.0.0.1:3306/${at.database}>`;
+        if (kind.startsWith('redis'))
+            return '<redis URL: redis://:PASSWORD@127.0.0.1:6379/0>';
+        if (kind === 'nats' || kind === 'tls')
+            return '<nats URL: nats://USER:PASSWORD@127.0.0.1:4222>';
+        return '<URL with its credentials>';
+    }
+    if ((Array.isArray(current) && current.every((item) => typeof item === 'string')) ||
+        (current === undefined && types.has('array') && !types.has('string')))
+        return ['<a random value of 32 or more characters: openssl rand -base64 48>'];
+    if (Array.isArray(current) || (current && typeof current === 'object'))
+        return '<the whole value of this option from the development dokebi.yaml, with production secrets>';
+    return '<secret>';
+}
+/** The settings sample of one instance: the sample without secrets, instance values, secrets list. */
+function instanceSample(sample, at, target, plugins, secrets, schemas) {
+    const document = parseDocument(sample, { version: '1.2' });
+    for (const path of secrets) {
+        // Only where the sample has the path: a section left empty (`connections:`) is null there.
+        const keys = ['options', ...path.split('.')];
+        let node = document.contents;
+        for (const key of keys.slice(0, -1))
+            node = isMap(node) || isSeq(node) ? node.get(key, true) : undefined;
+        if (isMap(node) || isSeq(node))
+            node.delete(keys.at(-1));
+    }
+    const set = (path, value, comment) => {
+        document.setIn(['options', ...path], value);
+        if (comment) {
+            const parent = document.getIn(['options', ...path.slice(0, -1)], true);
+            if (isMap(parent)) {
+                const pair = parent.items.find((item) => (isScalar(item.key) ? item.key.value : item.key) === path.at(-1));
+                if (pair) {
+                    // A key added by setIn is a plain string: make it a node that can carry the comment.
+                    if (!isScalar(pair.key))
+                        pair.key = document.createNode(pair.key);
+                    pair.key.commentBefore = ` ${comment}`;
+                }
+            }
+        }
+    };
+    if (plugins.includes('dokebi-web')) {
+        set(['dokebi-web', 'host'], '127.0.0.1', `deploy (${at.instance}): behind the reverse proxy on this server`);
+        set(['dokebi-web', 'port'], at.port);
+        set(['dokebi-web', 'trustProxy'], ['127.0.0.1', '::1'], 'the reverse proxy on this server; add its address when it runs elsewhere');
+    }
+    if (plugins.includes('dokebi-storage'))
+        set(['dokebi-storage', 'directory'], `${at.data}/storage`, `deploy (${at.instance}): outside the release folder`);
+    if (secrets.length) {
+        const list = document.createNode([...secrets]);
+        if (isSeq(list))
+            list.flow = false;
+        const pair = document.createPair('secrets', list);
+        pair.key.commentBefore =
+            ` deploy (${at.instance}, ${target}): these options come from the secrets file DOKEBI_SECRETS\n names (${at.secrets}, mode 0600); the app refuses to start while one is empty`;
+        const contents = document.contents;
+        if (isMap(contents))
+            contents.items.splice(1, 0, pair);
+    }
+    // The `# reloadable` marks stay on their key lines, as the CLI writes them (D-0154).
+    applyReloadableMarks(document, schemas);
+    return renderConfig(document);
+}
+/** The secrets sample of one instance: each secret path with a placeholder. */
+function secretsSample(at, secrets, sources, schemas) {
+    const document = parseDocument('schemaVersion: 1\noptions: {}\n', { version: '1.2' });
+    for (const path of secrets) {
+        const keys = path.split('.');
+        const current = sources
+            .map((options) => valueAt(options, keys))
+            .find((value) => value !== undefined);
+        const [section = '', ...rest] = keys;
+        document.setIn(['options', ...keys], placeholderFor(path, at, current, schemaTypes(schemas.get(section), rest)));
+    }
+    const options = document.get('options', true);
+    if (isMap(options))
+        options.flow = false;
+    document.commentBefore = ` The secrets of ${at.app} (${at.instance}): the paths only. The real file is ${at.secrets}
+ (mode 0600, owner ${at.unit}); its values come from your secret store and never from Git.
+ Replace each <placeholder> there; the settings sample lists the same paths under secrets:.`;
+    return renderConfig(document);
+}
+/** Writes the planned files in one transaction: new, unchanged, rewritten when untouched, else kept. */
+async function writeFiles(root, files, dryRun) {
+    const changed = [];
+    const unchanged = [];
+    const kept = [];
+    const warnings = [];
+    const tx = await Transaction.begin(root);
+    try {
+        for (const file of files) {
+            const current = await readOptional(await securePath(root, file.path));
+            if (current === file.content) {
+                unchanged.push(file.path);
+                continue;
+            }
+            const replaceable = current === undefined ||
+                untouched(file.path, current) ||
+                (file.path === 'DEPLOY.md' && current === DEPLOYMENT_FILES['DEPLOY.md']);
+            if (!replaceable) {
+                kept.push(file.path);
+                warnings.push({
+                    code: 'DEPLOY_FILE_KEPT',
+                    path: file.path,
+                    hint: `${file.path} was edited since deploy wrote it, so it is kept as it is; move it away and run the command again for the new version`,
+                });
+                continue;
+            }
+            const parent = dirname(file.path);
+            if (parent !== '.')
+                await tx.ensureDirectory(parent);
+            await tx.write(file.path, file.content);
+            changed.push(file.path);
+        }
+        if (!dryRun && changed.length)
+            await tx.commit();
+    }
+    catch (error) {
+        throw tx.failure(error);
+    }
+    finally {
+        await tx.close();
+    }
+    return { changed, unchanged, kept, warnings };
+}
+/** The instances deploy init wrote before (deploy/<name>/dokebi.example.yaml), with their ports. */
+async function knownInstances(root) {
+    const found = new Map();
+    let names;
+    try {
+        names = await readdir(join(root, 'deploy'));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return found;
+        throw error;
+    }
+    for (const name of names.sort()) {
+        if (!INSTANCE.test(name))
+            continue;
+        const text = await readOptional(join(root, 'deploy', name, EXAMPLE));
+        if (text === undefined)
+            continue;
+        const port = valueAt(parseConfig(text).options, ['dokebi-web', 'port']);
+        found.set(name, typeof port === 'number' ? port : (DEFAULT_PORTS[name] ?? 0));
+    }
+    return found;
+}
+/** `dokebi deploy init` (D-0184 §2). */
+export async function deployInit(input, options) {
+    const root = await realpath(input);
+    const state = await projectState(root);
+    const app = await appName(root);
+    const plugins = state.plugins.map((plugin) => optionsKey(plugin));
+    const names = [...new Set(options.instances)];
+    for (const name of names)
+        if (!INSTANCE.test(name))
+            throw new CliError('USAGE', `--instance ${name}: lowercase letters, digits and -, 1 to 24 characters, starting with a letter`, {
+                phase: 'arguments',
+            });
+    if (options.port !== undefined && names.length !== 1)
+        throw new CliError('USAGE', '--port names the port of one instance; give one --instance with it', {
+            phase: 'arguments',
+        });
+    const known = await knownInstances(root);
+    const ports = new Map();
+    for (const name of names) {
+        const port = options.port ?? known.get(name) ?? DEFAULT_PORTS[name];
+        if (port === undefined || port === 0)
+            throw new CliError('PORT_REQUIRED', `The instance ${name} needs a port: --port <n>`, {
+                phase: 'arguments',
+                details: {
+                    instance: name,
+                    fix: `npx dokebi deploy init --instance ${name} --port <a free port such as 3002>`,
+                },
+            });
+        ports.set(name, port);
+    }
+    // Instances on one server never share a port.
+    for (const [name, port] of [...known, ...ports]) {
+        const other = [...known, ...ports].find(([otherName, otherPort]) => otherName !== name && otherPort === port);
+        if (other)
+            throw new CliError('PORT_IN_USE', `The instances ${name} and ${other[0]} would both listen on 127.0.0.1:${port}`, {
+                phase: 'arguments',
+                details: {
+                    port,
+                    instances: [name, other[0]],
+                    fix: `give one of them another port: --instance ${name} --port <n>`,
+                },
+            });
+    }
+    const sample = await readOptional(await securePath(root, EXAMPLE));
+    if (sample === undefined)
+        throw new CliError('EXAMPLE_MISSING', `No ${EXAMPLE} to make the instance settings from`, {
+            phase: 'arguments',
+            details: {
+                file: EXAMPLE,
+                fix: `restore ${EXAMPLE} from version control (the CLI writes it and it belongs there)`,
+            },
+        });
+    const { paths: secrets, unreadable } = await secretPaths(root, sample);
+    debug('Deployment secrets found', { secrets });
+    const schemas = await reloadSchemas(root, state.plugins, state.settings ?? []);
+    const development = await readOptional(join(root, CONFIG_FILE));
+    const sources = [
+        ...(development === undefined ? [] : [parseConfig(development).options]),
+        parseConfig(sample).options,
+    ];
+    const all = [...new Set([...known.keys(), ...names])].sort((a, b) => a === 'production' ? -1 : b === 'production' ? 1 : a.localeCompare(b));
+    const layouts = all.map((name) => layout(app, name, ports.get(name) ?? known.get(name) ?? 0));
+    const files = [];
+    const add = (path, body) => files.push({ path, content: withMarker(path, body) });
+    for (const at of layouts.filter((item) => names.includes(item.instance))) {
+        add(`deploy/${at.instance}/${EXAMPLE}`, instanceSample(sample, at, options.target, plugins, secrets, schemas));
+        add(`deploy/${at.instance}/secrets.example.yaml`, secretsSample(at, secrets, sources, schemas));
+        if (options.target === 'systemd') {
+            add(`deploy/systemd/${at.unit}.service`, systemdUnit(at));
+            if (plugins.includes('dokebi-db')) {
+                add(`deploy/systemd/${at.unit}-backup.service`, backupService(at));
+                add(`deploy/systemd/${at.unit}-backup.timer`, backupTimer(at));
+            }
+        }
+        else
+            add(`deploy/compose/${at.instance}.yaml`, composeFile(at));
+    }
+    if (plugins.includes('dokebi-db')) {
+        add('deploy/backup.mjs', BACKUP_SCRIPT);
+        add('deploy/restore-drill.mjs', RESTORE_DRILL_SCRIPT);
+    }
+    if (options.target === 'compose')
+        for (const name of ['Dockerfile', '.dockerignore'])
+            if (!(await exists(join(root, name))))
+                files.push({ path: name, content: DEPLOYMENT_FILES[name] });
+    add('DEPLOY.md', deployGuide({ app, target: options.target, instances: layouts, plugins, secrets }));
+    const written = await writeFiles(root, files, options.dryRun === true);
+    written.warnings.push(...unreadableWarning(unreadable));
+    debug('Deployment files planned', {
+        target: options.target,
+        instances: names,
+        changed: written.changed.length,
+        kept: written.kept.length,
+        secrets: secrets.length,
+        dryRun: options.dryRun === true,
+    });
+    return {
+        app,
+        target: options.target,
+        instances: layouts.filter((item) => names.includes(item.instance)),
+        secrets,
+        changed: written.changed,
+        unchanged: written.unchanged,
+        kept: written.kept,
+        ...(written.warnings.length ? { warnings: written.warnings } : {}),
+        nextSteps: [
+            {
+                command: 'edit deploy/<instance>/dokebi.example.yaml',
+                why: 'fill its placeholders and dokebi-app.domains; it is the settings file of the instance on the server (no secret goes in it)',
+            },
+            ...(secrets.length
+                ? [
+                    {
+                        command: 'npx dokebi config secrets --json',
+                        why: `put ${secrets.join(', ')} into your secret store; the terminal writes them to the instance's secrets.yaml (mode 0600)`,
+                    },
+                ]
+                : []),
+            ...(plugins.includes('dokebi-web')
+                ? [
+                    {
+                        command: `npx dokebi deploy proxy --caddy --domain <host> --instance ${names[0]}`,
+                        why: 'the reverse proxy configuration of the instance (or --nginx)',
+                    },
+                ]
+                : []),
+            {
+                command: 'read DEPLOY.md',
+                why: 'server setup, the release order with migrations, rollback, backups',
+            },
+        ],
+    };
+}
+const DOMAIN = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,62}$/;
+/** `dokebi deploy proxy` (D-0184 §3). */
+export async function deployProxy(input, options) {
+    const root = await realpath(input);
+    const state = await projectState(root);
+    const app = await appName(root);
+    const plugins = state.plugins.map((plugin) => optionsKey(plugin));
+    const domains = [...new Set(options.domains.map((domain) => domain.toLowerCase()))];
+    for (const domain of domains)
+        if (!DOMAIN.test(domain))
+            throw new CliError('USAGE', `--domain ${domain}: a host name such as shop.example.com (no scheme, port or path)`, {
+                phase: 'arguments',
+            });
+    if (!plugins.includes('dokebi-web'))
+        throw new CliError('WEB_NOT_INSTALLED', 'This project serves no HTTP (no @dokebi/web), so it needs no reverse proxy', {
+            phase: 'arguments',
+            details: { fix: 'npx dokebi add @dokebi/web, or leave the proxy out' },
+        });
+    const samplePath = `deploy/${options.instance}/${EXAMPLE}`;
+    const sample = await readOptional(await securePath(root, samplePath));
+    if (sample === undefined)
+        throw new CliError('INSTANCE_UNKNOWN', `No ${samplePath}: deploy init has not made the instance ${options.instance}`, {
+            phase: 'arguments',
+            details: { fix: `npx dokebi deploy init --instance ${options.instance}` },
+        });
+    const settings = parseConfig(sample).options;
+    const web = settings['dokebi-web'] ?? {};
+    const port = typeof web.port === 'number' && web.port > 0 ? web.port : undefined;
+    if (port === undefined)
+        throw new CliError('PORT_REQUIRED', `${samplePath} sets no dokebi-web.port`, {
+            phase: 'arguments',
+            details: { fix: `set dokebi-web.port in ${samplePath} (deploy init writes it)` },
+        });
+    const at = layout(app, options.instance, port);
+    const routes = (web.healthRoutes ?? {});
+    const live = typeof routes.live === 'string' ? routes.live : '/health/live';
+    const ready = typeof routes.ready === 'string' ? routes.ready : '/health/ready';
+    const storage = settings['dokebi-storage'] ?? {};
+    const maxBodyBytes = Math.max(typeof web.maxBodyBytes === 'number' ? web.maxBodyBytes : 1_048_576, plugins.includes('dokebi-storage')
+        ? typeof storage.maxFileBytes === 'number'
+            ? storage.maxFileBytes
+            : 10_485_760
+        : 0);
+    const streams = ['dokebi-sse', 'dokebi-websocket', 'dokebi-websocket-hub', 'dokebi-mcp'].some((id) => plugins.includes(id));
+    const requestSeconds = Math.ceil((typeof web.requestTimeoutMs === 'number' ? web.requestTimeoutMs : 30_000) / 1000) +
+        5;
+    const proxyInput = {
+        at,
+        domains,
+        live,
+        ready,
+        maxBodyBytes,
+        readTimeoutSeconds: streams ? Math.max(3600, requestSeconds) : requestSeconds,
+        streams,
+    };
+    const file = options.proxy === 'caddy'
+        ? `deploy/proxy/${at.unit}.Caddyfile`
+        : `deploy/proxy/${at.unit}.nginx.conf`;
+    const body = options.proxy === 'caddy' ? caddyfile(proxyInput) : nginxConf(proxyInput);
+    const warnings = [];
+    const trusted = Array.isArray(web.trustProxy) ? web.trustProxy : [];
+    if (!trusted.includes('127.0.0.1') || !trusted.includes('::1'))
+        warnings.push({
+            code: 'TRUST_PROXY_MISSING',
+            path: `${samplePath}: dokebi-web.trustProxy`,
+            hint: 'the proxy connects from 127.0.0.1 or ::1, which dokebi-web.trustProxy does not list: the app would ignore X-Forwarded-Proto and -Host (http URLs, insecure cookies). Add both',
+        });
+    const appDomains = settings['dokebi-app']?.domains;
+    if (plugins.includes('dokebi-app')) {
+        const mapped = appDomains && typeof appDomains === 'object' ? Object.keys(appDomains) : [];
+        for (const domain of domains)
+            if (!mapped.includes(domain))
+                warnings.push({
+                    code: 'DOMAIN_NOT_MAPPED',
+                    path: `${samplePath}: dokebi-app.domains`,
+                    hint: `${domain} is not in dokebi-app.domains of the instance, so the app answers it as an unknown domain: add it (the same app as its development host)`,
+                });
+    }
+    const written = await writeFiles(root, [{ path: file, content: withMarker(file, body) }], options.dryRun === true);
+    debug('Proxy configuration planned', {
+        proxy: options.proxy,
+        instance: options.instance,
+        domains: domains.length,
+        streams,
+        warnings: warnings.length,
+    });
+    const all = [...written.warnings, ...warnings];
+    return {
+        app,
+        proxy: options.proxy,
+        instance: options.instance,
+        file,
+        domains,
+        changed: written.changed,
+        unchanged: written.unchanged,
+        kept: written.kept,
+        ...(all.length ? { warnings: all } : {}),
+        nextSteps: [
+            options.proxy === 'caddy'
+                ? {
+                    command: `sudo cp ${file} /etc/caddy/sites/${at.unit}.Caddyfile && sudo systemctl reload caddy`,
+                    why: 'import /etc/caddy/sites/* from the main Caddyfile',
+                }
+                : {
+                    command: `sudo cp ${file} /etc/nginx/conf.d/${at.unit}.conf && sudo nginx -t && sudo systemctl reload nginx`,
+                    why: 'after certbot made the certificate of the first domain',
+                },
+            {
+                command: `npx -y @dokebi/cli verify --remote https://${domains[0]} --json`,
+                why: 'checks TLS, the redirect, health and security headers through the proxy',
+            },
+        ],
+    };
+}

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.4.26";
+export declare const CLI_VERSION = "0.4.28";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,5 +1,5 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.4.26';
+export const CLI_VERSION = '0.4.28';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }

package/dist/production-doctor.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './project-inspector.js';
+/** The production diagnostics of the project at `root` (D-0184 §4). */
+export declare function productionDiagnostics(root: string, env?: NodeJS.ProcessEnv): Promise<Diagnostic[]>;