@dokebi/cli 0.4.26 → 0.4.28

package/dist/config-secrets.js

@@ -0,0 +1,226 @@
+// `dokebi config secrets` (D-0184): the secret option paths the app needs, by name only — where
+// each one comes from (dokebi.yaml or the secrets file DOKEBI_SECRETS names) and which are
+// missing. Values are never read into the result.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { applySecrets, ConfigError, parseConfig, readConfigFile, SECRETS_VARIABLE, } from '@dokebi/config';
+import { isPlaceholder } from './config-init.js';
+import { configShow, readSettings } from './config-show.js';
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { optionsKey } from './manifest.js';
+import { dependencyMap } from './npm-client.js';
+import { planLifecycle } from './plugin-lifecycle.js';
+import { readState } from './project-state.js';
+import { reloadSchemas } from './reloadable.js';
+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;
+}
+function empty(value) {
+    return (value === undefined ||
+        value === null ||
+        value === '' ||
+        isPlaceholder(value) ||
+        (Array.isArray(value) && (value.length === 0 || value.every(isPlaceholder))) ||
+        (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0));
+}
+/** The JSON Schema types the option at `keys` may have (properties, records, anyOf/oneOf). */
+export function schemaTypes(schema, keys) {
+    const types = new Set();
+    const walk = (node, rest, depth) => {
+        if (!node || typeof node !== 'object' || depth > 32)
+            return;
+        const value = node;
+        for (const branch of ['anyOf', 'oneOf', 'allOf'])
+            if (Array.isArray(value[branch]))
+                for (const item of value[branch])
+                    walk(item, rest, depth + 1);
+        if (!rest.length) {
+            if (typeof value.type === 'string')
+                types.add(value.type);
+            return;
+        }
+        const [key, ...tail] = rest;
+        const properties = value.properties;
+        if (properties && Object.hasOwn(properties, key))
+            walk(properties[key], tail, depth + 1);
+        else if (value.additionalProperties && typeof value.additionalProperties === 'object')
+            walk(value.additionalProperties, tail, depth + 1);
+        else if (/^\d+$/.test(key) && value.items)
+            walk(value.items, tail, depth + 1);
+    };
+    walk(schema, keys, 0);
+    return types;
+}
+/** The type of the option at `path` as `SecretEntry.type` says it. */
+function typeOf(schemas, path) {
+    const [section = '', ...rest] = path.split('.');
+    const types = [...schemaTypes(schemas.get(section), rest)].sort();
+    return types.length === 0 ? null : types.length === 1 ? types[0] : types;
+}
+/** The same failure as the app's start, as a CLI error with the paths and no values. */
+function configFailure(error) {
+    return new CliError(error.code, error.message, {
+        phase: 'arguments',
+        details: {
+            issues: error.issues.map((issue) => ({
+                path: issue.instancePath
+                    .split('/')
+                    .slice(1)
+                    .map((key) => key.replaceAll('~1', '/').replaceAll('~0', '~'))
+                    .join('.'),
+                keyword: issue.keyword,
+            })),
+            fix: error.fix,
+        },
+    });
+}
+/**
+ * The secrets the installed plugins generate at install (their plans' `configSecrets`, such as
+ * `dokebi-session.secrets`): each plugin needs one to start.
+ */
+export async function requiredSecretPaths(root, options) {
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    const projectPackages = Object.keys(dependencyMap(parseObject(await readFile(join(root, 'package.json'), 'utf8'), 'package.json')));
+    const paths = [];
+    // A plugin whose install module cannot run here (not installed: npm install) is named, so the
+    // list is never silently short.
+    const unreadable = [];
+    for (const plugin of state.plugins) {
+        let plan;
+        try {
+            plan = await planLifecycle({ base: root, plugin, options, plugins: state.plugins, projectPackages }, 'planInstall');
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.code !== 'PLUGIN_INSTALL_FAILED')
+                throw error;
+            unreadable.push(plugin.id);
+            continue;
+        }
+        for (const path of plan.configSecrets)
+            paths.push([optionsKey(plugin), ...path].join('.'));
+    }
+    return { paths, unreadable };
+}
+/** The warning for plugins whose generated secrets could not be read (their install modules). */
+export function unreadableWarning(plugins) {
+    return plugins.length
+        ? [
+            {
+                code: 'SECRETS_PLAN_UNREADABLE',
+                path: plugins.join(', '),
+                hint: 'the install modules of these plugins could not run (are their packages installed? npm install), so the secrets they generate are not in this list',
+            },
+        ]
+        : [];
+}
+/** `dokebi config secrets`: secret paths by name, where each is set, and the missing ones. */
+export async function configSecrets(root, env = process.env) {
+    const { target, source } = await readSettings(root);
+    let document;
+    try {
+        document = parseConfig(source);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw configFailure(error);
+        throw error;
+    }
+    const secretsFile = env[SECRETS_VARIABLE] || undefined;
+    // The merged options (conflicts and an unsafe file refuse as at start); the list is checked
+    // below, so a missing listed secret is reported instead of thrown.
+    let merged = document.options;
+    let secretsText;
+    let secretOptions;
+    if (secretsFile !== undefined) {
+        try {
+            merged = (await applySecrets({ schemaVersion: 1, options: document.options }, secretsFile))
+                .options;
+            secretsText = await readConfigFile(secretsFile);
+            secretOptions = parseConfig(secretsText).options;
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                throw configFailure(error);
+            throw error;
+        }
+    }
+    const fromConfig = new Set((await configShow(root, undefined, { source, file: target.file })).secrets);
+    const fromSecrets = new Set(secretsText === undefined
+        ? []
+        : (await configShow(root, undefined, { source: secretsText, file: secretsFile }))
+            .secrets);
+    const planned = await requiredSecretPaths(root, document.options);
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    // The types tell a tool that writes the secrets file a list from a text (Studio v2, 11-01).
+    const schemas = await reloadSchemas(root, state.plugins, state.settings ?? []);
+    const required = new Set(planned.paths);
+    const listed = document.secrets ?? [];
+    const paths = [...new Set([...fromConfig, ...fromSecrets, ...listed, ...required])].sort();
+    const secrets = paths.map((path) => {
+        const set = !empty(valueAt(merged, path.split('.')));
+        return {
+            path,
+            source: !set ? null : !empty(valueAt(secretOptions, path.split('.'))) ? 'secrets' : 'config',
+            listed: listed.includes(path),
+            required: required.has(path),
+            type: typeOf(schemas, path),
+        };
+    });
+    const missing = secrets.filter((entry) => entry.source === null).map((entry) => entry.path);
+    const warnings = [
+        ...unreadableWarning(planned.unreadable),
+        ...(secretsFile === undefined
+            ? []
+            : secrets
+                .filter((entry) => entry.source === 'config' && fromConfig.has(entry.path))
+                .map((entry) => ({
+                code: 'SECRET_IN_CONFIG_FILE',
+                path: entry.path,
+                hint: `${target.file} holds this secret although ${SECRETS_VARIABLE} names a secrets file: move it there (the configuration file is the one deploy/ keeps without secrets)`,
+            }))),
+    ];
+    debug('Configuration secrets listed', {
+        secrets: secrets.length,
+        missing: missing.length,
+        listed: listed.length,
+        secretsFile: secretsFile !== undefined,
+    });
+    return {
+        file: target.file,
+        secretsFile: secretsFile ?? null,
+        listed,
+        secrets,
+        missing,
+        ...(warnings.length ? { warnings } : {}),
+        ...(missing.length
+            ? {
+                nextSteps: [
+                    {
+                        command: secretsFile === undefined
+                            ? `${SECRETS_VARIABLE}=<the 0600 secrets file> npx dokebi config secrets --json`
+                            : `edit ${secretsFile}`,
+                        why: `set ${missing.join(', ')} (the app refuses to start without the listed ones: CONFIG_SECRETS_MISSING)`,
+                    },
+                ],
+            }
+            : {}),
+    };
+}
+/** The result for people: one line per path. */
+export function configSecretsText(result) {
+    const lines = result.secrets.map((entry) => `${entry.source === null ? 'MISSING' : entry.source.padEnd(7)} ${entry.path}${entry.type === 'array' ? ' (a list)' : ''}${entry.listed ? ' (listed)' : ''}${entry.required ? ' (required)' : ''}`);
+    return `${lines.join('\n') || 'no secret options'}\n${result.missing.length ? `missing: ${result.missing.join(', ')}` : 'no secret missing'}${(result.warnings ?? [])
+        .map((warning) => `\nwarning: ${warning.code} (${warning.path}): ${warning.hint}`)
+        .join('')}\n`;
+}

package/dist/deploy-scripts.d.ts

@@ -0,0 +1,4 @@
+/** deploy/backup.mjs */
+export declare const BACKUP_SCRIPT = "// Backs up the app's databases (D-0184): every dokebi-db connection whose URL\n// (connections.<name>.options.url) is postgres or mongodb, read from the settings the app reads (DOKEBI_CONFIG and the secrets file that\n// DOKEBI_SECRETS names). Each backup is <DOKEBI_BACKUP_DIR>/<connection>/<UTC time>.<pgdump|archive.gz>\n// (mode 0600); older ones are removed except the newest per day, per week and per month\n// (DOKEBI_BACKUP_KEEP=days,weeks,months, default 7,4,6). One JSON line on stdout; exit 1 when a\n// connection failed. pg_dump (PostgreSQL client tools of the server's major version or later)\n// and mongodump (MongoDB Database Tools) must be on PATH.\n//\n//   DOKEBI_CONFIG=/etc/<app>/<instance>/dokebi.yaml DOKEBI_SECRETS=/etc/<app>/<instance>/secrets.yaml \\\n//   DOKEBI_BACKUP_DIR=/var/backups/<app>/<instance> node deploy/backup.mjs\n//\n// DOKEBI_BACKUP_CONNECTIONS=main,reports limits it to those connections.\nimport { spawn } from 'node:child_process';\nimport { openSync, closeSync, fsyncSync } from 'node:fs';\nimport { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { loadConfig } from '@dokebi/core';\n\nprocess.umask(0o077);\nconst started = Date.now();\nconst NAME = /^(\\d{8}T\\d{6}Z)\\.(pgdump|archive\\.gz)$/;\n\nfunction fail(message) {\n  process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\\n`);\n  process.exit(1);\n}\n\nconst configFile = process.env.DOKEBI_CONFIG;\nconst folder = process.env.DOKEBI_BACKUP_DIR;\nif (!configFile) fail('DOKEBI_CONFIG is not set: the settings file of the instance');\nif (!folder) fail('DOKEBI_BACKUP_DIR is not set: the folder that keeps the backups');\nconst keep = (process.env.DOKEBI_BACKUP_KEEP ?? '7,4,6').split(',').map(Number);\nif (keep.length !== 3 || keep.some((value) => !Number.isSafeInteger(value) || value < 0))\n  fail('DOKEBI_BACKUP_KEEP is days,weeks,months (whole numbers), e.g. 7,4,6');\nconst only = process.env.DOKEBI_BACKUP_CONNECTIONS?.split(',').filter(Boolean);\n\n/** postgres or mongodb by the URL scheme; anything else is not backed up here. */\nfunction kindOf(url) {\n  const scheme = url.slice(0, url.indexOf(':')).toLowerCase();\n  if (scheme === 'postgres' || scheme === 'postgresql') return 'postgres';\n  if (scheme === 'mongodb' || scheme === 'mongodb+srv') return 'mongodb';\n  return undefined;\n}\n\n/** Runs a tool with stdout into `file`; stderr is kept for the error (it never holds the password). */\nfunction run(command, args, env, file) {\n  return new Promise((resolve, reject) => {\n    const fd = openSync(file, 'wx', 0o600);\n    let stderr = '';\n    const child = spawn(command, args, { env, stdio: ['ignore', fd, 'pipe'] });\n    child.stderr.setEncoding('utf8');\n    child.stderr.on('data', (chunk) => {\n      stderr = (stderr + chunk).slice(-4000);\n    });\n    child.once('error', (error) => {\n      closeSync(fd);\n      reject(new Error(`${command} could not run: ${error.message}`));\n    });\n    child.once('close', (code, signal) => {\n      try {\n        fsyncSync(fd);\n      } finally {\n        closeSync(fd);\n      }\n      if (code === 0) resolve();\n      else reject(new Error(`${command} exited with ${code ?? signal}: ${stderr.trim()}`));\n    });\n  });\n}\n\nasync function backup(name, url, target) {\n  const kind = kindOf(url);\n  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\\.\\d+Z$/, 'Z');\n  const directory = join(folder, name);\n  await mkdir(directory, { recursive: true, mode: 0o700 });\n  const file = join(directory, `${stamp}.${kind === 'postgres' ? 'pgdump' : 'archive.gz'}`);\n  const partial = `${file}.partial`;\n  const begun = Date.now();\n  try {\n    if (kind === 'postgres') {\n      const parsed = new URL(url);\n      const password = decodeURIComponent(parsed.password);\n      parsed.password = '';\n      await run(\n        'pg_dump',\n        ['--format=custom', '--no-owner', '--no-privileges', `--dbname=${parsed.href}`],\n        { ...process.env, PGPASSWORD: password },\n        partial,\n      );\n    } else {\n      // The URI (with its password) goes in a 0600 file, never on the command line.\n      const options = join(directory, `.${stamp}.mongodump.yaml`);\n      await writeFile(options, `uri: ${JSON.stringify(url)}\\n`, { mode: 0o600, flag: 'wx' });\n      try {\n        await run('mongodump', [`--config=${options}`, '--archive', '--gzip'], process.env, partial);\n      } finally {\n        await rm(options, { force: true });\n      }\n    }\n    await rename(partial, file);\n  } catch (error) {\n    await rm(partial, { force: true });\n    throw error;\n  }\n  const { size } = await stat(file);\n  target.push({ connection: name, kind, file, bytes: size, ms: Date.now() - begun });\n}\n\n/** The newest backup per day, per ISO week and per month, as many of each as DOKEBI_BACKUP_KEEP says. */\nasync function prune(name) {\n  const directory = join(folder, name);\n  const files = (await readdir(directory)).filter((entry) => NAME.test(entry)).sort().reverse();\n  const kept = new Set();\n  const pick = (count, period) => {\n    const seen = new Set();\n    for (const file of files) {\n      if (seen.size >= count) break;\n      const key = period(file.slice(0, 8));\n      if (seen.has(key)) continue;\n      seen.add(key);\n      kept.add(file);\n    }\n  };\n  const week = (day) => {\n    const date = new Date(Date.UTC(+day.slice(0, 4), +day.slice(4, 6) - 1, +day.slice(6, 8)));\n    const thursday = new Date(date);\n    thursday.setUTCDate(date.getUTCDate() + 3 - ((date.getUTCDay() + 6) % 7));\n    const first = new Date(Date.UTC(thursday.getUTCFullYear(), 0, 4));\n    return `${thursday.getUTCFullYear()}-${Math.round((thursday - first) / 604800000 + 1)}`;\n  };\n  pick(keep[0], (day) => day);\n  pick(keep[1], week);\n  pick(keep[2], (day) => day.slice(0, 6));\n  const removed = files.filter((file) => !kept.has(file));\n  for (const file of removed) await rm(join(directory, file));\n  // A partial file of a run that died is removed after a day.\n  for (const entry of await readdir(directory))\n    if (entry.endsWith('.partial')) {\n      const { mtimeMs } = await stat(join(directory, entry));\n      if (Date.now() - mtimeMs > 86_400_000) await rm(join(directory, entry), { force: true });\n    }\n  return removed.length;\n}\n\nlet document;\ntry {\n  document = await loadConfig(configFile);\n} catch (error) {\n  fail(`settings could not be read: ${error.code ?? ''} ${error.message}`);\n}\nconst connections = document.options['dokebi-db']?.connections ?? {};\nconst done = [];\nconst failed = [];\nconst skipped = [];\nlet removed = 0;\nfor (const [name, connection] of Object.entries(connections)) {\n  if (only && !only.includes(name)) continue;\n  // options.dokebi-db.connections.<name> = { adapter, options: { url, \u2026 } }\n  const url = typeof connection?.options?.url === 'string' ? connection.options.url : undefined;\n  if (!url || !kindOf(url)) {\n    skipped.push({ connection: name, reason: url ? 'not postgres or mongodb' : 'no url' });\n    continue;\n  }\n  try {\n    await backup(name, url, done);\n    removed += await prune(name);\n  } catch (error) {\n    failed.push({ connection: name, error: error.message });\n  }\n}\nconst ok = failed.length === 0 && done.length > 0;\nprocess.stdout.write(\n  `${JSON.stringify({ ok, backups: done, failed, skipped, removed, ms: Date.now() - started })}\\n`,\n);\nif (!ok) process.exitCode = 1;\n";
+/** deploy/restore-drill.mjs */
+export declare const RESTORE_DRILL_SCRIPT = "// Restore drill (D-0184): proves the newest backup of a connection can be restored. It restores\n// it into DOKEBI_RESTORE_URL (an empty scratch database, never the live one: refused when it is\n// the same database) and compares the restored database with the live one: tables or\n// collections, and the rows of the migration history (dokebi_migrations). One JSON line; exit 1\n// when the restore failed or the restored database is empty. Run it every month and after a\n// change of the PostgreSQL or MongoDB version.\n//\n//   DOKEBI_CONFIG=/etc/<app>/<instance>/dokebi.yaml DOKEBI_SECRETS=/etc/<app>/<instance>/secrets.yaml \\\n//   DOKEBI_BACKUP_DIR=/var/backups/<app>/<instance> DOKEBI_RESTORE_URL=postgres://...<scratch db> \\\n//   node deploy/restore-drill.mjs\n//\n// DOKEBI_RESTORE_CONNECTION picks the connection (default main). DOKEBI_RESTORE_URL is a secret:\n// put it in the environment of this run only (a systemd-run --property=EnvironmentFile=...).\nimport { spawn } from 'node:child_process';\nimport { createReadStream } from 'node:fs';\nimport { readdir, rm, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { loadConfig } from '@dokebi/core';\n\nprocess.umask(0o077);\nconst started = Date.now();\nfunction fail(message, extra = {}) {\n  process.stdout.write(`${JSON.stringify({ ok: false, error: message, ...extra })}\\n`);\n  process.exit(1);\n}\nconst configFile = process.env.DOKEBI_CONFIG;\nconst folder = process.env.DOKEBI_BACKUP_DIR;\nconst target = process.env.DOKEBI_RESTORE_URL;\nconst name = process.env.DOKEBI_RESTORE_CONNECTION || 'main';\nif (!configFile || !folder || !target)\n  fail('DOKEBI_CONFIG, DOKEBI_BACKUP_DIR and DOKEBI_RESTORE_URL must be set');\n\nlet document;\ntry {\n  document = await loadConfig(configFile);\n} catch (error) {\n  fail(`settings could not be read: ${error.code ?? ''} ${error.message}`);\n}\nconst live = document.options['dokebi-db']?.connections?.[name]?.options?.url;\nif (typeof live !== 'string') fail(`no url for the dokebi-db connection ${name}`);\nconst scheme = (url) => url.slice(0, url.indexOf(':')).toLowerCase();\nconst kind = ['postgres', 'postgresql'].includes(scheme(live))\n  ? 'postgres'\n  : ['mongodb', 'mongodb+srv'].includes(scheme(live))\n    ? 'mongodb'\n    : fail(`the connection ${name} is not postgres or mongodb`);\nif (kind !== (['postgres', 'postgresql'].includes(scheme(target)) ? 'postgres' : 'mongodb'))\n  fail('DOKEBI_RESTORE_URL is not the same kind of database as the connection');\nconst where = (url) => {\n  const parsed = new URL(url);\n  return `${parsed.hostname}:${parsed.port}/${parsed.pathname.slice(1)}`;\n};\nif (where(live) === where(target)) fail('DOKEBI_RESTORE_URL names the live database; use a scratch one');\n\nconst extension = kind === 'postgres' ? '.pgdump' : '.archive.gz';\nlet entries = [];\ntry {\n  entries = await readdir(join(folder, name));\n} catch (error) {\n  if (error.code !== 'ENOENT') throw error;\n}\nconst files = entries\n  .filter((file) => /^\\d{8}T\\d{6}Z/.test(file) && file.endsWith(extension))\n  .sort();\nconst newest = files.at(-1);\nif (!newest) fail(`no backup of ${name} in ${join(folder, name)}`);\nconst backup = join(folder, name, newest);\n\nfunction run(command, args, env, input) {\n  return new Promise((resolve, reject) => {\n    let stderr = '';\n    const child = spawn(command, args, { env, stdio: ['pipe', 'ignore', 'pipe'] });\n    child.stderr.setEncoding('utf8');\n    child.stderr.on('data', (chunk) => {\n      stderr = (stderr + chunk).slice(-4000);\n    });\n    child.once('error', (error) => reject(new Error(`${command} could not run: ${error.message}`)));\n    // A tool that stops reading (it failed) breaks the pipe: its exit code says why.\n    child.stdin.on('error', (error) => {\n      stderr = `${stderr}\\n(input: ${error.code ?? error.message})`.slice(-4000);\n    });\n    const source = createReadStream(input);\n    source.once('error', (error) => {\n      child.kill();\n      reject(new Error(`the backup could not be read: ${error.message}`));\n    });\n    child.once('close', (code, signal) =>\n      code === 0\n        ? resolve()\n        : reject(new Error(`${command} exited with ${code ?? signal}: ${stderr.trim()}`)),\n    );\n    source.pipe(child.stdin);\n  });\n}\n\nasync function postgresCounts(url) {\n  const { default: pg } = await import('pg');\n  const client = new pg.Client({ connectionString: url });\n  await client.connect();\n  try {\n    const tables = await client.query(\n      \"select count(*)::int as n from information_schema.tables where table_type = 'BASE TABLE' and table_schema not in ('pg_catalog', 'information_schema')\",\n    );\n    const history = await client.query(\"select to_regclass('dokebi_migrations') is not null as present\");\n    const migrations = history.rows[0].present\n      ? (await client.query('select count(*)::int as n from dokebi_migrations')).rows[0].n\n      : null;\n    return { tables: tables.rows[0].n, migrations };\n  } finally {\n    await client.end();\n  }\n}\n\nasync function mongoCounts(url) {\n  const { MongoClient } = await import('mongodb');\n  const client = new MongoClient(url);\n  await client.connect();\n  try {\n    const db = client.db();\n    const collections = (await db.listCollections({}, { nameOnly: true }).toArray()).filter(\n      (item) => !item.name.startsWith('system.'),\n    );\n    const migrations = collections.some((item) => item.name === 'dokebi_migrations')\n      ? await db.collection('dokebi_migrations').countDocuments()\n      : null;\n    return { tables: collections.length, migrations };\n  } finally {\n    await client.close();\n  }\n}\n\ntry {\n  if (kind === 'postgres') {\n    const parsed = new URL(target);\n    const password = decodeURIComponent(parsed.password);\n    parsed.password = '';\n    await run(\n      'pg_restore',\n      ['--clean', '--if-exists', '--no-owner', '--no-privileges', `--dbname=${parsed.href}`],\n      { ...process.env, PGPASSWORD: password },\n      backup,\n    );\n  } else {\n    const from = new URL(live).pathname.slice(1);\n    const to = new URL(target).pathname.slice(1);\n    // A database in the URI would act as a --db filter (nothing of the backup matches it): the\n    // URI names the server only, --nsFrom/--nsTo the databases.\n    const server = new URL(target);\n    server.pathname = '/';\n    const options = join(folder, name, '.restore-drill.mongorestore.yaml');\n    await writeFile(options, `uri: ${JSON.stringify(server.href)}\\n`, { mode: 0o600 });\n    try {\n      await run(\n        'mongorestore',\n        [`--config=${options}`, '--archive', '--gzip', '--drop', `--nsFrom=${from}.*`, `--nsTo=${to}.*`],\n        process.env,\n        backup,\n      );\n    } finally {\n      await rm(options, { force: true });\n    }\n  }\n} catch (error) {\n  fail(error.message, { backup });\n}\nconst count = kind === 'postgres' ? postgresCounts : mongoCounts;\nconst [restored, current] = await Promise.all([count(target), count(live)]);\nconst ok = restored.tables > 0;\nconst notes = [];\nif (restored.tables !== current.tables)\n  notes.push(`the live database has ${current.tables} tables or collections, the backup ${restored.tables}`);\nif (restored.migrations !== current.migrations)\n  notes.push('the live migration history differs from the backup (a migration ran since)');\nprocess.stdout.write(\n  `${JSON.stringify({ ok, connection: name, kind, backup, restored, live: current, notes, ms: Date.now() - started })}\\n`,\n);\nif (!ok) process.exitCode = 1;\n";

package/dist/deploy-scripts.js

@@ -0,0 +1,361 @@
+// The backup and restore-drill scripts `dokebi deploy init` writes into deploy/ (D-0184 §6).
+// They are the project's files: plain ESM run with `node` in a release folder, using the app's
+// own @dokebi/core (the settings with the secrets file) and its database drivers (pg, mongodb).
+// Secrets never reach a command line: pg_dump and pg_restore get the password in PGPASSWORD,
+// mongodump and mongorestore read the URI from a 0600 file passed with --config.
+/** deploy/backup.mjs */
+export const BACKUP_SCRIPT = `// Backs up the app's databases (D-0184): every dokebi-db connection whose URL
+// (connections.<name>.options.url) is postgres or mongodb, read from the settings the app reads (DOKEBI_CONFIG and the secrets file that
+// DOKEBI_SECRETS names). Each backup is <DOKEBI_BACKUP_DIR>/<connection>/<UTC time>.<pgdump|archive.gz>
+// (mode 0600); older ones are removed except the newest per day, per week and per month
+// (DOKEBI_BACKUP_KEEP=days,weeks,months, default 7,4,6). One JSON line on stdout; exit 1 when a
+// connection failed. pg_dump (PostgreSQL client tools of the server's major version or later)
+// and mongodump (MongoDB Database Tools) must be on PATH.
+//
+//   DOKEBI_CONFIG=/etc/<app>/<instance>/dokebi.yaml DOKEBI_SECRETS=/etc/<app>/<instance>/secrets.yaml \\
+//   DOKEBI_BACKUP_DIR=/var/backups/<app>/<instance> node deploy/backup.mjs
+//
+// DOKEBI_BACKUP_CONNECTIONS=main,reports limits it to those connections.
+import { spawn } from 'node:child_process';
+import { openSync, closeSync, fsyncSync } from 'node:fs';
+import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig } from '@dokebi/core';
+
+process.umask(0o077);
+const started = Date.now();
+const NAME = /^(\\d{8}T\\d{6}Z)\\.(pgdump|archive\\.gz)$/;
+
+function fail(message) {
+  process.stdout.write(\`\${JSON.stringify({ ok: false, error: message })}\\n\`);
+  process.exit(1);
+}
+
+const configFile = process.env.DOKEBI_CONFIG;
+const folder = process.env.DOKEBI_BACKUP_DIR;
+if (!configFile) fail('DOKEBI_CONFIG is not set: the settings file of the instance');
+if (!folder) fail('DOKEBI_BACKUP_DIR is not set: the folder that keeps the backups');
+const keep = (process.env.DOKEBI_BACKUP_KEEP ?? '7,4,6').split(',').map(Number);
+if (keep.length !== 3 || keep.some((value) => !Number.isSafeInteger(value) || value < 0))
+  fail('DOKEBI_BACKUP_KEEP is days,weeks,months (whole numbers), e.g. 7,4,6');
+const only = process.env.DOKEBI_BACKUP_CONNECTIONS?.split(',').filter(Boolean);
+
+/** postgres or mongodb by the URL scheme; anything else is not backed up here. */
+function kindOf(url) {
+  const scheme = url.slice(0, url.indexOf(':')).toLowerCase();
+  if (scheme === 'postgres' || scheme === 'postgresql') return 'postgres';
+  if (scheme === 'mongodb' || scheme === 'mongodb+srv') return 'mongodb';
+  return undefined;
+}
+
+/** Runs a tool with stdout into \`file\`; stderr is kept for the error (it never holds the password). */
+function run(command, args, env, file) {
+  return new Promise((resolve, reject) => {
+    const fd = openSync(file, 'wx', 0o600);
+    let stderr = '';
+    const child = spawn(command, args, { env, stdio: ['ignore', fd, 'pipe'] });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      stderr = (stderr + chunk).slice(-4000);
+    });
+    child.once('error', (error) => {
+      closeSync(fd);
+      reject(new Error(\`\${command} could not run: \${error.message}\`));
+    });
+    child.once('close', (code, signal) => {
+      try {
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      if (code === 0) resolve();
+      else reject(new Error(\`\${command} exited with \${code ?? signal}: \${stderr.trim()}\`));
+    });
+  });
+}
+
+async function backup(name, url, target) {
+  const kind = kindOf(url);
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\\.\\d+Z$/, 'Z');
+  const directory = join(folder, name);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = join(directory, \`\${stamp}.\${kind === 'postgres' ? 'pgdump' : 'archive.gz'}\`);
+  const partial = \`\${file}.partial\`;
+  const begun = Date.now();
+  try {
+    if (kind === 'postgres') {
+      const parsed = new URL(url);
+      const password = decodeURIComponent(parsed.password);
+      parsed.password = '';
+      await run(
+        'pg_dump',
+        ['--format=custom', '--no-owner', '--no-privileges', \`--dbname=\${parsed.href}\`],
+        { ...process.env, PGPASSWORD: password },
+        partial,
+      );
+    } else {
+      // The URI (with its password) goes in a 0600 file, never on the command line.
+      const options = join(directory, \`.\${stamp}.mongodump.yaml\`);
+      await writeFile(options, \`uri: \${JSON.stringify(url)}\\n\`, { mode: 0o600, flag: 'wx' });
+      try {
+        await run('mongodump', [\`--config=\${options}\`, '--archive', '--gzip'], process.env, partial);
+      } finally {
+        await rm(options, { force: true });
+      }
+    }
+    await rename(partial, file);
+  } catch (error) {
+    await rm(partial, { force: true });
+    throw error;
+  }
+  const { size } = await stat(file);
+  target.push({ connection: name, kind, file, bytes: size, ms: Date.now() - begun });
+}
+
+/** The newest backup per day, per ISO week and per month, as many of each as DOKEBI_BACKUP_KEEP says. */
+async function prune(name) {
+  const directory = join(folder, name);
+  const files = (await readdir(directory)).filter((entry) => NAME.test(entry)).sort().reverse();
+  const kept = new Set();
+  const pick = (count, period) => {
+    const seen = new Set();
+    for (const file of files) {
+      if (seen.size >= count) break;
+      const key = period(file.slice(0, 8));
+      if (seen.has(key)) continue;
+      seen.add(key);
+      kept.add(file);
+    }
+  };
+  const week = (day) => {
+    const date = new Date(Date.UTC(+day.slice(0, 4), +day.slice(4, 6) - 1, +day.slice(6, 8)));
+    const thursday = new Date(date);
+    thursday.setUTCDate(date.getUTCDate() + 3 - ((date.getUTCDay() + 6) % 7));
+    const first = new Date(Date.UTC(thursday.getUTCFullYear(), 0, 4));
+    return \`\${thursday.getUTCFullYear()}-\${Math.round((thursday - first) / 604800000 + 1)}\`;
+  };
+  pick(keep[0], (day) => day);
+  pick(keep[1], week);
+  pick(keep[2], (day) => day.slice(0, 6));
+  const removed = files.filter((file) => !kept.has(file));
+  for (const file of removed) await rm(join(directory, file));
+  // A partial file of a run that died is removed after a day.
+  for (const entry of await readdir(directory))
+    if (entry.endsWith('.partial')) {
+      const { mtimeMs } = await stat(join(directory, entry));
+      if (Date.now() - mtimeMs > 86_400_000) await rm(join(directory, entry), { force: true });
+    }
+  return removed.length;
+}
+
+let document;
+try {
+  document = await loadConfig(configFile);
+} catch (error) {
+  fail(\`settings could not be read: \${error.code ?? ''} \${error.message}\`);
+}
+const connections = document.options['dokebi-db']?.connections ?? {};
+const done = [];
+const failed = [];
+const skipped = [];
+let removed = 0;
+for (const [name, connection] of Object.entries(connections)) {
+  if (only && !only.includes(name)) continue;
+  // options.dokebi-db.connections.<name> = { adapter, options: { url, … } }
+  const url = typeof connection?.options?.url === 'string' ? connection.options.url : undefined;
+  if (!url || !kindOf(url)) {
+    skipped.push({ connection: name, reason: url ? 'not postgres or mongodb' : 'no url' });
+    continue;
+  }
+  try {
+    await backup(name, url, done);
+    removed += await prune(name);
+  } catch (error) {
+    failed.push({ connection: name, error: error.message });
+  }
+}
+const ok = failed.length === 0 && done.length > 0;
+process.stdout.write(
+  \`\${JSON.stringify({ ok, backups: done, failed, skipped, removed, ms: Date.now() - started })}\\n\`,
+);
+if (!ok) process.exitCode = 1;
+`;
+/** deploy/restore-drill.mjs */
+export const RESTORE_DRILL_SCRIPT = `// Restore drill (D-0184): proves the newest backup of a connection can be restored. It restores
+// it into DOKEBI_RESTORE_URL (an empty scratch database, never the live one: refused when it is
+// the same database) and compares the restored database with the live one: tables or
+// collections, and the rows of the migration history (dokebi_migrations). One JSON line; exit 1
+// when the restore failed or the restored database is empty. Run it every month and after a
+// change of the PostgreSQL or MongoDB version.
+//
+//   DOKEBI_CONFIG=/etc/<app>/<instance>/dokebi.yaml DOKEBI_SECRETS=/etc/<app>/<instance>/secrets.yaml \\
+//   DOKEBI_BACKUP_DIR=/var/backups/<app>/<instance> DOKEBI_RESTORE_URL=postgres://...<scratch db> \\
+//   node deploy/restore-drill.mjs
+//
+// DOKEBI_RESTORE_CONNECTION picks the connection (default main). DOKEBI_RESTORE_URL is a secret:
+// put it in the environment of this run only (a systemd-run --property=EnvironmentFile=...).
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig } from '@dokebi/core';
+
+process.umask(0o077);
+const started = Date.now();
+function fail(message, extra = {}) {
+  process.stdout.write(\`\${JSON.stringify({ ok: false, error: message, ...extra })}\\n\`);
+  process.exit(1);
+}
+const configFile = process.env.DOKEBI_CONFIG;
+const folder = process.env.DOKEBI_BACKUP_DIR;
+const target = process.env.DOKEBI_RESTORE_URL;
+const name = process.env.DOKEBI_RESTORE_CONNECTION || 'main';
+if (!configFile || !folder || !target)
+  fail('DOKEBI_CONFIG, DOKEBI_BACKUP_DIR and DOKEBI_RESTORE_URL must be set');
+
+let document;
+try {
+  document = await loadConfig(configFile);
+} catch (error) {
+  fail(\`settings could not be read: \${error.code ?? ''} \${error.message}\`);
+}
+const live = document.options['dokebi-db']?.connections?.[name]?.options?.url;
+if (typeof live !== 'string') fail(\`no url for the dokebi-db connection \${name}\`);
+const scheme = (url) => url.slice(0, url.indexOf(':')).toLowerCase();
+const kind = ['postgres', 'postgresql'].includes(scheme(live))
+  ? 'postgres'
+  : ['mongodb', 'mongodb+srv'].includes(scheme(live))
+    ? 'mongodb'
+    : fail(\`the connection \${name} is not postgres or mongodb\`);
+if (kind !== (['postgres', 'postgresql'].includes(scheme(target)) ? 'postgres' : 'mongodb'))
+  fail('DOKEBI_RESTORE_URL is not the same kind of database as the connection');
+const where = (url) => {
+  const parsed = new URL(url);
+  return \`\${parsed.hostname}:\${parsed.port}/\${parsed.pathname.slice(1)}\`;
+};
+if (where(live) === where(target)) fail('DOKEBI_RESTORE_URL names the live database; use a scratch one');
+
+const extension = kind === 'postgres' ? '.pgdump' : '.archive.gz';
+let entries = [];
+try {
+  entries = await readdir(join(folder, name));
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error;
+}
+const files = entries
+  .filter((file) => /^\\d{8}T\\d{6}Z/.test(file) && file.endsWith(extension))
+  .sort();
+const newest = files.at(-1);
+if (!newest) fail(\`no backup of \${name} in \${join(folder, name)}\`);
+const backup = join(folder, name, newest);
+
+function run(command, args, env, input) {
+  return new Promise((resolve, reject) => {
+    let stderr = '';
+    const child = spawn(command, args, { env, stdio: ['pipe', 'ignore', 'pipe'] });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      stderr = (stderr + chunk).slice(-4000);
+    });
+    child.once('error', (error) => reject(new Error(\`\${command} could not run: \${error.message}\`)));
+    // A tool that stops reading (it failed) breaks the pipe: its exit code says why.
+    child.stdin.on('error', (error) => {
+      stderr = \`\${stderr}\\n(input: \${error.code ?? error.message})\`.slice(-4000);
+    });
+    const source = createReadStream(input);
+    source.once('error', (error) => {
+      child.kill();
+      reject(new Error(\`the backup could not be read: \${error.message}\`));
+    });
+    child.once('close', (code, signal) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(\`\${command} exited with \${code ?? signal}: \${stderr.trim()}\`)),
+    );
+    source.pipe(child.stdin);
+  });
+}
+
+async function postgresCounts(url) {
+  const { default: pg } = await import('pg');
+  const client = new pg.Client({ connectionString: url });
+  await client.connect();
+  try {
+    const tables = await client.query(
+      "select count(*)::int as n from information_schema.tables where table_type = 'BASE TABLE' and table_schema not in ('pg_catalog', 'information_schema')",
+    );
+    const history = await client.query("select to_regclass('dokebi_migrations') is not null as present");
+    const migrations = history.rows[0].present
+      ? (await client.query('select count(*)::int as n from dokebi_migrations')).rows[0].n
+      : null;
+    return { tables: tables.rows[0].n, migrations };
+  } finally {
+    await client.end();
+  }
+}
+
+async function mongoCounts(url) {
+  const { MongoClient } = await import('mongodb');
+  const client = new MongoClient(url);
+  await client.connect();
+  try {
+    const db = client.db();
+    const collections = (await db.listCollections({}, { nameOnly: true }).toArray()).filter(
+      (item) => !item.name.startsWith('system.'),
+    );
+    const migrations = collections.some((item) => item.name === 'dokebi_migrations')
+      ? await db.collection('dokebi_migrations').countDocuments()
+      : null;
+    return { tables: collections.length, migrations };
+  } finally {
+    await client.close();
+  }
+}
+
+try {
+  if (kind === 'postgres') {
+    const parsed = new URL(target);
+    const password = decodeURIComponent(parsed.password);
+    parsed.password = '';
+    await run(
+      'pg_restore',
+      ['--clean', '--if-exists', '--no-owner', '--no-privileges', \`--dbname=\${parsed.href}\`],
+      { ...process.env, PGPASSWORD: password },
+      backup,
+    );
+  } else {
+    const from = new URL(live).pathname.slice(1);
+    const to = new URL(target).pathname.slice(1);
+    // A database in the URI would act as a --db filter (nothing of the backup matches it): the
+    // URI names the server only, --nsFrom/--nsTo the databases.
+    const server = new URL(target);
+    server.pathname = '/';
+    const options = join(folder, name, '.restore-drill.mongorestore.yaml');
+    await writeFile(options, \`uri: \${JSON.stringify(server.href)}\\n\`, { mode: 0o600 });
+    try {
+      await run(
+        'mongorestore',
+        [\`--config=\${options}\`, '--archive', '--gzip', '--drop', \`--nsFrom=\${from}.*\`, \`--nsTo=\${to}.*\`],
+        process.env,
+        backup,
+      );
+    } finally {
+      await rm(options, { force: true });
+    }
+  }
+} catch (error) {
+  fail(error.message, { backup });
+}
+const count = kind === 'postgres' ? postgresCounts : mongoCounts;
+const [restored, current] = await Promise.all([count(target), count(live)]);
+const ok = restored.tables > 0;
+const notes = [];
+if (restored.tables !== current.tables)
+  notes.push(\`the live database has \${current.tables} tables or collections, the backup \${restored.tables}\`);
+if (restored.migrations !== current.migrations)
+  notes.push('the live migration history differs from the backup (a migration ran since)');
+process.stdout.write(
+  \`\${JSON.stringify({ ok, connection: name, kind, backup, restored, live: current, notes, ms: Date.now() - started })}\\n\`,
+);
+if (!ok) process.exitCode = 1;
+`;

package/dist/deploy-templates.d.ts

@@ -0,0 +1,46 @@
+/** Where one instance lives on the server. */
+export interface InstanceLayout {
+    readonly app: string;
+    readonly instance: string;
+    /** Local port of the app (127.0.0.1). */
+    readonly port: number;
+    /** systemd unit, system user and journald identifier; compose project name. */
+    readonly unit: string;
+    readonly settings: string;
+    readonly secrets: string;
+    readonly code: string;
+    readonly data: string;
+    readonly logs: string;
+    readonly backups: string;
+    /** The suggested database name: <app>_<instance>. */
+    readonly database: string;
+}
+export declare function layout(app: string, instance: string, port: number): InstanceLayout;
+export declare function systemdUnit(at: InstanceLayout): string;
+export declare function backupService(at: InstanceLayout): string;
+export declare function backupTimer(at: InstanceLayout): string;
+export declare function composeFile(at: InstanceLayout): string;
+export interface GuideInput {
+    readonly app: string;
+    readonly target: 'systemd' | 'compose';
+    readonly instances: readonly InstanceLayout[];
+    /** The installed plugin ids. */
+    readonly plugins: readonly string[];
+    /** The secret paths the samples leave to the secrets file, per instance (the same list). */
+    readonly secrets: readonly string[];
+}
+/** DEPLOY.md: the instance table, setup, a release, rollback, backups (D-0184 §5, §6). */
+export declare function deployGuide(input: GuideInput): string;
+export interface ProxyInput {
+    readonly at: InstanceLayout;
+    readonly domains: readonly string[];
+    readonly live: string;
+    readonly ready: string;
+    /** Largest request body the app takes, in bytes. */
+    readonly maxBodyBytes: number;
+    /** The proxy's read timeout, seconds (long when the app keeps SSE or WebSocket connections). */
+    readonly readTimeoutSeconds: number;
+    readonly streams: boolean;
+}
+export declare function caddyfile(input: ProxyInput): string;
+export declare function nginxConf(input: ProxyInput): string;