@dokebi/cli 0.4.2 → 0.4.27

package/dist/registry.d.ts

@@ -27,8 +27,16 @@ export declare function registryBase(value: string | undefined): string | undefi
 export type VersionManifest = {
     dokebi?: {
         core?: string;
+        id?: string;
+        dependencies?: {
+            name?: string;
+            version?: string;
+            package?: string;
+            optional?: boolean;
+        }[];
     };
     deprecated?: string;
+    peerDependencies?: Record<string, string>;
 };
 export type Packument = ({
     readonly status: 'found';
@@ -47,6 +55,63 @@ export type Packument = ({
  * a plain auth-free GET. `offline` covers network and server errors, and npm `offline=true`.
  */
 export declare function fetchPackument(name: string, cwd?: string): Promise<Packument>;
+/** An installed package version that the registry npm now uses for it does not have (D-0138). */
+export interface MissingOnRegistry {
+    readonly package: string;
+    readonly version: string;
+    /** The registry npm uses for the package now (registryFor in the project folder). */
+    readonly registry: string;
+    /** Where package-lock.json says this copy came from, when it says. */
+    readonly installedFrom?: string;
+}
+/**
+ * D-0138: the installed packages (an exact registry version each) whose version is not on the
+ * registry npm now uses for them in `cwd`. npm re-reads them from that registry to check the
+ * peers of what it adds, so a project installed from another registry (another `.npmrc`, a shell
+ * without the `@dokebi:registry` it was installed with) fails with an ERESOLVE whose "Found:
+ * @dokebi/core@undefined" says nothing of the cause. A package the registry does not know at all
+ * counts as missing; a registry that cannot be read (offline, an error) proves nothing and is
+ * skipped (debug log). A lock `resolved` under the same registry is not asked again.
+ */
+export declare function missingOnRegistry(installed: readonly {
+    readonly package: string;
+    readonly version: string;
+    readonly resolved?: string;
+}[], cwd?: string): Promise<MissingOnRegistry[]>;
+/**
+ * What the project asks of a version `add` or `upgrade` picks: the peers it names must accept the
+ * versions installed, and the installed plugins must accept it (their manifest dependency ranges,
+ * optional ones too). Without this, the highest core-compatible version could need a newer
+ * @dokebi/web than the project has, and npm stopped the install with ERESOLVE.
+ */
+export interface ProjectConstraints {
+    /** Installed npm packages and their versions (the package being changed left out). */
+    readonly installed: Readonly<Record<string, string>>;
+    /** Plugin ids of installed packages, by package name, for the fix commands. */
+    readonly ids: Readonly<Record<string, string>>;
+    /** Ranges installed plugins declare for a plugin id (their manifest dependencies). */
+    readonly required: Readonly<Record<string, readonly {
+        plugin: string;
+        range: string;
+    }[]>>;
+}
+/** Why a version does not fit the project: a peer range, or a dependent plugin's range. */
+export type VersionConflict = {
+    readonly kind: 'peer';
+    readonly package: string;
+    readonly range: string;
+    readonly installed: string;
+} | {
+    readonly kind: 'dependent';
+    readonly plugin: string;
+    readonly range: string;
+};
+/** The conflicts of `version` (with manifest `manifest`) with the installed project. */
+export declare function versionConflicts(version: string, manifest: VersionManifest, constraints: ProjectConstraints): VersionConflict[];
+/** What `version` of `name` needs, in one sentence part per conflict. */
+export declare function describeConflicts(name: string, version: string, conflicts: readonly VersionConflict[]): string;
+/** The commands that clear `conflicts` (each upgrade first), then `then`. */
+export declare function conflictFix(conflicts: readonly VersionConflict[], constraints: ProjectConstraints, then: string): string;
 /**
  * The highest release whose `dokebi.core` range accepts `coreVersion` (a version without the
  * field counts as compatible). Prereleases are never chosen (semver's `includePrerelease:
@@ -56,6 +121,19 @@ export declare function fetchPackument(name: string, cwd?: string): Promise<Pack
 export declare function highestCompatible(packument: {
     readonly versions: Readonly<Record<string, VersionManifest>>;
 }, coreVersion: string): string | null;
+export interface VersionPick {
+    /** The chosen version: compatible with the core and, with constraints, with the project. */
+    readonly version: string | null;
+    /** The version the core alone would choose, when the project's packages hold it back. */
+    readonly heldBack?: {
+        readonly version: string;
+        readonly conflicts: readonly VersionConflict[];
+    };
+}
+/** highestCompatible, and with `constraints` only a version without conflicts (see heldBack). */
+export declare function pickVersion(packument: {
+    readonly versions: Readonly<Record<string, VersionManifest>>;
+}, coreVersion: string, constraints?: ProjectConstraints): VersionPick;
 export interface Resolution {
     readonly package: string;
     readonly version: string;
@@ -71,9 +149,27 @@ export interface Resolution {
  * compatible with the project core, from the registry npm uses for that package in `cwd`, else
  * from the CLI snapshot. Throws NOT_PUBLISHED (the registry has no such package) or
  * NO_COMPATIBLE_VERSION. Returns undefined with an offline marker when neither source knows the
- * package.
+ * package. With `project`, the version must also fit the installed packages (pickVersion): a
+ * newer one they hold back is returned as `heldBack`, and when none fits it is
+ * INCOMPATIBLE_VERSION whose fix upgrades them first, then runs `project.next`.
  */
-export declare function resolveVersion(name: string, coreVersion: string, catalog: Catalog, cwd?: string): Promise<{
+export declare function resolveVersion(name: string, coreVersion: string, catalog: Catalog, cwd?: string, project?: {
+    readonly constraints: ProjectConstraints;
+    readonly next: string;
+}): Promise<{
     resolution?: Resolution;
     offline?: string;
+    heldBack?: VersionPick['heldBack'];
+    /** The registry's manifest of the chosen version (its peers and dokebi dependencies). */
+    manifest?: VersionManifest;
 }>;
+/**
+ * The versions of the required plugins `manifest` names with a package (`dokebi.dependencies`,
+ * not optional) that the project lacks, and theirs in turn: `<package>@<version>` each, the
+ * highest in the required range that fits the core and the installed packages. npm installs a
+ * missing peer at the highest version of its range and never tries a lower one, so a session
+ * for core 0.4.1 got the newest @dokebi/web, which needed a newer core, and the install stopped
+ * with ERESOLVE. A dependency no version fits is INCOMPATIBLE_VERSION (fix: upgrade first, then
+ * `then`); one the registry cannot tell is left to npm. At most 16, like the automatic installs.
+ */
+export declare function companionVersions(manifest: VersionManifest, coreVersion: string, constraints: ProjectConstraints, cwd: string, then: string, skip?: (name: string) => boolean): Promise<string[]>;

package/dist/registry.js

@@ -5,7 +5,6 @@ import valid from 'semver/functions/valid.js';
 import { findPackage } from './catalog.js';
 import { debug, describeError } from './diagnostics.js';
 import { CliError } from './errors.js';
-import { runNpm } from './npm-client.js';
 const FETCH_TIMEOUT_MS = 8000;
 const NPM_CONFIG_TIMEOUT_MS = 30_000;
 /** npm's built-in default registry. */
@@ -36,6 +35,9 @@ export function registryFor(name, cwd = process.cwd()) {
 }
 async function askNpm(cwd, scope) {
     const keys = ['registry', 'offline', ...(scope ? [`${scope}:registry`] : [])];
+    // Loaded here: npm-client pulls in the manifest and YAML modules, which `plugins list` without
+    // --online never needs.
+    const runNpm = (await import('./npm-client.js')).runNpm;
     let values;
     try {
         const result = await runNpm(cwd, ['config', 'get', ...keys], {
@@ -145,8 +147,86 @@ export async function fetchPackument(name, cwd = process.cwd()) {
         };
     }
 }
+/**
+ * D-0138: the installed packages (an exact registry version each) whose version is not on the
+ * registry npm now uses for them in `cwd`. npm re-reads them from that registry to check the
+ * peers of what it adds, so a project installed from another registry (another `.npmrc`, a shell
+ * without the `@dokebi:registry` it was installed with) fails with an ERESOLVE whose "Found:
+ * @dokebi/core@undefined" says nothing of the cause. A package the registry does not know at all
+ * counts as missing; a registry that cannot be read (offline, an error) proves nothing and is
+ * skipped (debug log). A lock `resolved` under the same registry is not asked again.
+ */
+export async function missingOnRegistry(installed, cwd = process.cwd()) {
+    const found = await Promise.all(installed.map(async (item) => {
+        const settings = await registryFor(item.package, cwd);
+        if (item.resolved?.startsWith(settings.url))
+            return undefined;
+        const packument = await fetchPackument(item.package, cwd);
+        if (packument.status === 'offline') {
+            debug('Registry not readable; installed version not checked', {
+                package: item.package,
+                registry: packument.registry,
+                error: packument.error,
+            });
+            return undefined;
+        }
+        if (packument.status === 'found' && Object.hasOwn(packument.versions, item.version))
+            return undefined;
+        return {
+            package: item.package,
+            version: item.version,
+            registry: packument.registry,
+            ...(item.resolved ? { installedFrom: withoutCredentials(item.resolved) } : {}),
+        };
+    }));
+    return found.filter((item) => item !== undefined);
+}
+/** A lock `resolved` URL without `user:password@` (a file path or other text is kept). */
+function withoutCredentials(value) {
+    if (!/^https?:\/\//.test(value))
+        return value;
+    try {
+        const url = new URL(value);
+        url.username = '';
+        url.password = '';
+        return url.href;
+    }
+    catch (error) {
+        debug('Lock resolved value is not a URL', { error: describeError(error) });
+        return value;
+    }
+}
 /** `0.0.0-<tag>`: a name-reserving placeholder, never a real release. */
 const PLACEHOLDER = /^0\.0\.0-/;
+/** The conflicts of `version` (with manifest `manifest`) with the installed project. */
+export function versionConflicts(version, manifest, constraints) {
+    const found = [];
+    for (const [name, range] of Object.entries(manifest.peerDependencies ?? {})) {
+        const installed = constraints.installed[name];
+        if (installed !== undefined && valid(installed) && !satisfies(installed, range))
+            found.push({ kind: 'peer', package: name, range, installed });
+    }
+    const id = manifest.dokebi?.id;
+    for (const item of (id !== undefined && constraints.required[id]) || [])
+        if (!satisfies(version, item.range))
+            found.push({ kind: 'dependent', plugin: item.plugin, range: item.range });
+    return found;
+}
+/** What `version` of `name` needs, in one sentence part per conflict. */
+export function describeConflicts(name, version, conflicts) {
+    return conflicts
+        .map((item) => item.kind === 'peer'
+        ? `${name} ${version} needs ${item.package} ${item.range} and the project has ${item.installed}`
+        : `the installed ${item.plugin} accepts ${name} ${item.range} only`)
+        .join('; ');
+}
+/** The commands that clear `conflicts` (each upgrade first), then `then`. */
+export function conflictFix(conflicts, constraints, then) {
+    const steps = conflicts.map((item) => item.kind === 'peer'
+        ? `npx dokebi upgrade ${constraints.ids[item.package] ?? item.package} (to a version in ${item.range})`
+        : `npx dokebi upgrade ${item.plugin} (to a version that accepts it)`);
+    return `${[...new Set(steps)].join(', ')}, then ${then}`;
+}
 /**
  * The highest release whose `dokebi.core` range accepts `coreVersion` (a version without the
  * field counts as compatible). Prereleases are never chosen (semver's `includePrerelease:
@@ -154,6 +234,10 @@ const PLACEHOLDER = /^0\.0\.0-/;
  * placeholder. A deprecated version is chosen only when no compatible one is undeprecated.
  */
 export function highestCompatible(packument, coreVersion) {
+    return pickVersion(packument, coreVersion).version;
+}
+/** highestCompatible, and with `constraints` only a version without conflicts (see heldBack). */
+export function pickVersion(packument, coreVersion, constraints) {
     const candidates = Object.entries(packument.versions)
         .filter(([version, manifest]) => {
         if (!valid(version) || prerelease(version) || PLACEHOLDER.test(version))
@@ -162,16 +246,26 @@ export function highestCompatible(packument, coreVersion) {
         return range === undefined || satisfies(coreVersion, range);
     })
         .sort(([a], [b]) => rcompare(a, b));
-    return candidates.find(([, manifest]) => !manifest.deprecated)?.[0] ?? candidates[0]?.[0] ?? null;
+    const choose = (list) => list.find(([, manifest]) => !manifest.deprecated)?.[0] ?? list[0]?.[0] ?? null;
+    const top = choose(candidates);
+    if (!constraints || top === null)
+        return { version: top };
+    const version = choose(candidates.filter(([candidate, manifest]) => versionConflicts(candidate, manifest, constraints).length === 0));
+    if (version === top)
+        return { version };
+    const conflicts = versionConflicts(top, packument.versions[top] ?? {}, constraints);
+    return { version, heldBack: { version: top, conflicts } };
 }
 /**
  * Picks the version `dokebi add <package>` installs when no version is given: the highest one
  * compatible with the project core, from the registry npm uses for that package in `cwd`, else
  * from the CLI snapshot. Throws NOT_PUBLISHED (the registry has no such package) or
  * NO_COMPATIBLE_VERSION. Returns undefined with an offline marker when neither source knows the
- * package.
+ * package. With `project`, the version must also fit the installed packages (pickVersion): a
+ * newer one they hold back is returned as `heldBack`, and when none fits it is
+ * INCOMPATIBLE_VERSION whose fix upgrades them first, then runs `project.next`.
  */
-export async function resolveVersion(name, coreVersion, catalog, cwd = process.cwd()) {
+export async function resolveVersion(name, coreVersion, catalog, cwd = process.cwd(), project) {
     const found = await fetchPackument(name, cwd);
     if (found.status === 'missing')
         throw new CliError('NOT_PUBLISHED', `${name} is not published on the registry`, {
@@ -179,7 +273,24 @@ export async function resolveVersion(name, coreVersion, catalog, cwd = process.c
             phase: 'install',
         });
     if (found.status === 'found') {
-        const version = highestCompatible(found, coreVersion);
+        const { version, heldBack } = pickVersion(found, coreVersion, project?.constraints);
+        if (!version && heldBack && project) {
+            const [first] = heldBack.conflicts;
+            throw new CliError('INCOMPATIBLE_VERSION', `No version of ${name} for core ${coreVersion} fits the installed packages: ${describeConflicts(name, heldBack.version, heldBack.conflicts)}`, {
+                details: {
+                    package: name,
+                    version: heldBack.version,
+                    ...(first?.kind === 'peer'
+                        ? { requires: first.package, range: first.range, installed: first.installed }
+                        : first
+                            ? { dependent: first.plugin, range: first.range }
+                            : {}),
+                    conflicts: heldBack.conflicts,
+                    fix: conflictFix(heldBack.conflicts, project.constraints, project.next),
+                },
+                phase: 'plan',
+            });
+        }
         if (!version)
             throw new CliError('NO_COMPATIBLE_VERSION', `No version of ${name} supports @dokebi/core ${coreVersion}`, {
                 details: {
@@ -200,6 +311,8 @@ export async function resolveVersion(name, coreVersion, catalog, cwd = process.c
                 registry: found.registry,
                 ...(deprecated ? { deprecated } : {}),
             },
+            ...(heldBack ? { heldBack } : {}),
+            manifest: found.versions[version] ?? {},
         };
     }
     const known = findPackage(catalog, name);
@@ -210,3 +323,56 @@ export async function resolveVersion(name, coreVersion, catalog, cwd = process.c
         };
     return { offline: found.error };
 }
+/**
+ * The versions of the required plugins `manifest` names with a package (`dokebi.dependencies`,
+ * not optional) that the project lacks, and theirs in turn: `<package>@<version>` each, the
+ * highest in the required range that fits the core and the installed packages. npm installs a
+ * missing peer at the highest version of its range and never tries a lower one, so a session
+ * for core 0.4.1 got the newest @dokebi/web, which needed a newer core, and the install stopped
+ * with ERESOLVE. A dependency no version fits is INCOMPATIBLE_VERSION (fix: upgrade first, then
+ * `then`); one the registry cannot tell is left to npm. At most 16, like the automatic installs.
+ */
+export async function companionVersions(manifest, coreVersion, constraints, cwd, then, skip = () => false) {
+    const specs = [];
+    const seen = new Set();
+    const queue = [manifest];
+    while (queue.length && specs.length < 16) {
+        const current = queue.shift();
+        for (const dependency of current.dokebi?.dependencies ?? []) {
+            const name = dependency.package;
+            const range = dependency.version;
+            if (dependency.optional || !name || !range || seen.has(name) || skip(name))
+                continue;
+            seen.add(name);
+            if (constraints.installed[name] !== undefined)
+                continue;
+            const found = await fetchPackument(name, cwd);
+            if (found.status !== 'found')
+                continue;
+            const inRange = Object.fromEntries(Object.entries(found.versions).filter(([version]) => valid(version) !== null && satisfies(version, range)));
+            const { version, heldBack } = pickVersion({ versions: inRange }, coreVersion, constraints);
+            if (!version) {
+                if (!heldBack)
+                    continue;
+                throw new CliError('INCOMPATIBLE_VERSION', `No version of ${name} in ${range} (required by the package being installed) fits the installed packages: ${describeConflicts(name, heldBack.version, heldBack.conflicts)}`, {
+                    details: {
+                        package: name,
+                        range,
+                        version: heldBack.version,
+                        conflicts: heldBack.conflicts,
+                        fix: conflictFix(heldBack.conflicts, constraints, then),
+                    },
+                    phase: 'plan',
+                });
+            }
+            debug('Picked the version of a required plugin npm would install as a peer', {
+                package: name,
+                range,
+                version,
+            });
+            specs.push(`${name}@${version}`);
+            queue.push(found.versions[version] ?? {});
+        }
+    }
+    return specs;
+}

package/dist/reloadable.d.ts

@@ -0,0 +1,35 @@
+import { type Document } from 'yaml';
+import { type PluginManifest } from './manifest.js';
+/** The comment the CLI writes after a reloadable key. */
+export declare const RELOADABLE_MARK = "reloadable";
+type Schema = Readonly<Record<string, unknown>>;
+/**
+ * Core's part of options.logging (D-0047): level and plugins, both reloadable. With @dokebi/logger
+ * installed its schema (which has them, marked the same way) is used instead.
+ */
+export declare const CORE_LOGGING_SCHEMA: Schema;
+/** Whether a change at `path` inside a section with `schema` applies without a restart. */
+export declare function reloadableAt(schema: unknown, path: readonly (string | number)[]): boolean;
+/**
+ * The schema of each section of dokebi.yaml a running app can reload: every installed plugin
+ * with an options schema (its own section, `logging` for the logger host), core's `reload` and,
+ * without a logger plugin, core's `logging`. A schema that cannot be read is left out (nothing is
+ * marked for it).
+ */
+export declare function reloadSchemas(root: string, plugins: readonly PluginManifest[], settings?: readonly string[]): Promise<Map<string, unknown>>;
+/**
+ * Puts `# reloadable` after each topmost reloadable key under `options` and takes stale marks
+ * away (an option that is no longer reloadable), leaving every other comment and value as it is.
+ * Returns how many marks changed, and how many were moved back onto their key line.
+ */
+export declare function applyReloadableMarks(document: Document, schemas: ReadonlyMap<string, unknown>): {
+    readonly changed: number;
+    readonly moved: number;
+};
+/**
+ * `source` (dokebi.yaml or dokebi.example.yaml) with the reloadable marks of `schemas`; the same
+ * text when no mark changes (nothing is re-rendered then) or when it is not a readable YAML
+ * document (the caller reports that).
+ */
+export declare function markReloadable(source: string, schemas: ReadonlyMap<string, unknown>): string;
+export {};

package/dist/reloadable.js

@@ -0,0 +1,257 @@
+// D-0154: which options of dokebi.yaml a running app reads again, from the options schemas
+// (`x-dokebi-reloadable: true` on an option, covering everything under it) and core's own
+// sections. The CLI marks them in the YAML it writes (a trailing `# reloadable` comment on the
+// topmost reloadable key present) and in `config show`, so a person or an AI sees which edits
+// apply without a restart (`dokebi reload`, or saving the file while the app watches it).
+import { loadSchema } from '@dokebi/config';
+import { RELOADABLE_KEYWORD, reloadOptions } from '@dokebi/core';
+import { isCollection, isMap, isScalar, isSeq, parseDocument, Scalar, } from 'yaml';
+import { renderConfig } from './configuration.js';
+import { debug } from './diagnostics.js';
+import { optionsKey } from './manifest.js';
+import { readSettingsSchema } from './settings.js';
+import { packageFile } from './workspace.js';
+/** The comment the CLI writes after a reloadable key. */
+export const RELOADABLE_MARK = 'reloadable';
+const MARK_TOKEN = /(^|\s|·)reloadable(?=\s|$)/;
+/**
+ * Core's part of options.logging (D-0047): level and plugins, both reloadable. With @dokebi/logger
+ * installed its schema (which has them, marked the same way) is used instead.
+ */
+export const CORE_LOGGING_SCHEMA = Object.freeze({
+    type: 'object',
+    properties: {
+        level: { [RELOADABLE_KEYWORD]: true },
+        plugins: { [RELOADABLE_KEYWORD]: true },
+    },
+});
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const COMPOSED = ['anyOf', 'oneOf', 'allOf'];
+/** A schema node and the forms it composes (no `$ref`: the generated schemas have none). */
+function forms(node, depth = 0) {
+    const result = [node];
+    if (depth > 8)
+        return result;
+    for (const keyword of COMPOSED) {
+        const list = node[keyword];
+        if (Array.isArray(list))
+            for (const item of list)
+                if (record(item))
+                    result.push(...forms(item, depth + 1));
+    }
+    return result;
+}
+/** The schema nodes one step down (a property, a map value, an array item). */
+function children(nodes, segment) {
+    const next = [];
+    for (const node of nodes)
+        for (const form of forms(node)) {
+            if (typeof segment === 'number') {
+                if (record(form.items))
+                    next.push(form.items);
+                continue;
+            }
+            const properties = record(form.properties) ? form.properties : undefined;
+            const own = properties?.[segment];
+            if (record(own))
+                next.push(own);
+            else if (record(form.additionalProperties))
+                next.push(form.additionalProperties);
+        }
+    return next;
+}
+function marked(nodes) {
+    if (!nodes.length)
+        return false;
+    // Every form that has the key must mark it (a form that changes the shape needs a restart).
+    return nodes.every((node) => forms(node).some((form) => form[RELOADABLE_KEYWORD] === true));
+}
+/** Whether a change at `path` inside a section with `schema` applies without a restart. */
+export function reloadableAt(schema, path) {
+    if (!record(schema) || !path.length)
+        return false;
+    let nodes = [schema];
+    for (const segment of path) {
+        nodes = children(nodes, segment);
+        if (!nodes.length)
+            return false;
+        if (marked(nodes))
+            return true;
+    }
+    return false;
+}
+/**
+ * The schema of each section of dokebi.yaml a running app can reload: every installed plugin
+ * with an options schema (its own section, `logging` for the logger host), core's `reload` and,
+ * without a logger plugin, core's `logging`. A schema that cannot be read is left out (nothing is
+ * marked for it).
+ */
+export async function reloadSchemas(root, plugins, settings = []) {
+    const schemas = new Map([
+        ['logging', CORE_LOGGING_SCHEMA],
+        ['reload', reloadOptions.schema],
+    ]);
+    for (const plugin of plugins) {
+        if (!plugin.optionsSchema)
+            continue;
+        try {
+            schemas.set(optionsKey(plugin), await loadSchema(await packageFile(root, plugin.packageName, plugin.optionsSchema)));
+        }
+        catch (error) {
+            // Reported where the schema is used to check options (INVALID_OPTIONS_SCHEMA); here the
+            // section keeps its marks as they are (a staged install is not readable here yet).
+            schemas.delete(optionsKey(plugin));
+            debug('Options schema not read for the reloadable marks', {
+                plugin: plugin.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // D-0155: the settings sections of the application, from the schema beside each declaration.
+    for (const section of settings) {
+        try {
+            const schema = await readSettingsSchema(root, section);
+            if (schema)
+                schemas.set(section, schema);
+        }
+        catch (error) {
+            debug('Settings schema not read for the reloadable marks', {
+                section,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return schemas;
+}
+/** The comment of a pair that holds the mark: the value's, or the key line of a block. */
+function hasMark(pair) {
+    const key = pair.key;
+    const value = pair.value;
+    if (key && MARK_TOKEN.test(key.comment ?? ''))
+        return true;
+    if (value && MARK_TOKEN.test(value.comment ?? ''))
+        return true;
+    // A key comment of a block collection is read back as the first line before its value.
+    const before = value?.commentBefore?.split('\n')[0] ?? '';
+    return isCollection(value) && !value.flow && before.trim() === RELOADABLE_MARK;
+}
+function withoutMark(comment) {
+    if (!comment)
+        return undefined;
+    const rest = comment
+        .replace(/\s*·\s*reloadable(?=\s|$)/, '')
+        .replace(/^\s*reloadable(?=\s|$)\s*(·\s*)?/, ' ')
+        .replace(/\s+$/, '');
+    return rest.trim() ? rest : undefined;
+}
+function addMark(pair) {
+    // A key set as a plain string (document.set) becomes a node that can carry the comment.
+    if (!isScalar(pair.key))
+        pair.key = new Scalar(pair.key);
+    const key = pair.key;
+    const value = pair.value;
+    if (value && isCollection(value) && !value.flow) {
+        // `key: # reloadable` above the block.
+        key.comment = ` ${RELOADABLE_MARK}`;
+        return;
+    }
+    const target = value ?? key;
+    const existing = target.comment;
+    target.comment = existing?.trim() ? `${existing} · ${RELOADABLE_MARK}` : ` ${RELOADABLE_MARK}`;
+}
+/**
+ * A mark written on the key line of a block (`targets: # reloadable`) is read back as the first
+ * comment line before its value; put it back on the key line so it is rendered there again.
+ */
+function normalizeMark(pair) {
+    const key = pair.key;
+    const value = pair.value;
+    if (!key || !value || !isCollection(value) || value.flow || !value.commentBefore)
+        return false;
+    const lines = value.commentBefore.split('\n');
+    if (lines[0]?.trim() !== RELOADABLE_MARK)
+        return false;
+    lines.shift();
+    value.commentBefore = lines.length ? lines.join('\n') : null;
+    key.comment = ` ${RELOADABLE_MARK}`;
+    return true;
+}
+function removeMark(pair) {
+    const key = pair.key;
+    const value = pair.value;
+    if (key)
+        key.comment = withoutMark(key.comment) ?? null;
+    if (value)
+        value.comment = withoutMark(value.comment) ?? null;
+    if (value && isCollection(value) && !value.flow && value.commentBefore) {
+        const lines = value.commentBefore.split('\n');
+        if (lines[0]?.trim() === RELOADABLE_MARK)
+            lines.shift();
+        value.commentBefore = lines.length ? lines.join('\n') : null;
+    }
+}
+/**
+ * Puts `# reloadable` after each topmost reloadable key under `options` and takes stale marks
+ * away (an option that is no longer reloadable), leaving every other comment and value as it is.
+ * Returns how many marks changed, and how many were moved back onto their key line.
+ */
+export function applyReloadableMarks(document, schemas) {
+    const options = document.get('options', true);
+    if (!isMap(options))
+        return { changed: 0, moved: 0 };
+    let changed = 0;
+    let moved = 0;
+    const visit = (node, schema, path, under) => {
+        if (isMap(node))
+            for (const pair of node.items) {
+                const key = isScalar(pair.key) ? pair.key.value : pair.key;
+                if (typeof key !== 'string')
+                    continue;
+                const at = [...path, key];
+                const reloadable = !under && reloadableAt(schema, at);
+                const mark = reloadable;
+                if (mark && !hasMark(pair)) {
+                    addMark(pair);
+                    changed++;
+                }
+                else if (!mark && hasMark(pair)) {
+                    removeMark(pair);
+                    changed++;
+                }
+                else if (mark && normalizeMark(pair))
+                    moved++;
+                visit(pair.value, schema, at, under || reloadable);
+            }
+        else if (isSeq(node))
+            node.items.forEach((item, index) => {
+                visit(item, schema, [...path, index], under);
+            });
+    };
+    for (const pair of options.items) {
+        const section = isScalar(pair.key) ? pair.key.value : undefined;
+        // A section whose schema is not known here keeps its marks as they are.
+        if (typeof section !== 'string' || !schemas.has(section))
+            continue;
+        visit(pair.value, schemas.get(section), [], false);
+    }
+    return { changed, moved };
+}
+/**
+ * `source` (dokebi.yaml or dokebi.example.yaml) with the reloadable marks of `schemas`; the same
+ * text when no mark changes (nothing is re-rendered then) or when it is not a readable YAML
+ * document (the caller reports that).
+ */
+export function markReloadable(source, schemas) {
+    const document = parseDocument(source, { version: '1.2' });
+    if (document.errors.length)
+        return source;
+    const { changed, moved } = applyReloadableMarks(document, schemas);
+    if (!changed && !moved)
+        return source;
+    if (changed)
+        debug('Reloadable options marked in the configuration', { changed });
+    // A mark read back before its block goes back on the key line (rendered as it was written).
+    return renderConfig(document);
+}