@dokebi/cli 0.4.2 → 0.4.26

package/dist/settings.d.ts

@@ -0,0 +1,48 @@
+import { CliError } from './errors.js';
+export declare const SETTINGS_FOLDER = "src/shared/settings";
+/** Section names: as core's SETTINGS_SECTION (lower-case word, at most 64 characters). */
+export declare const SETTINGS_SECTION: RegExp;
+/** Core's own sections (options.logging, options.reload): never application settings. */
+export declare const RESERVED_SECTIONS: ReadonlySet<string>;
+export declare const settingsFile: (section: string) => string;
+export declare const settingsSchemaFile: (section: string) => string;
+/** The camelCase name of the export a settings file default-exports (`survey-limits` → surveyLimits). */
+export declare function settingsIdentifier(section: string): string;
+/** The file `settings add` writes: one reloadable and one restart-only option to start from. */
+export declare function settingsSource(section: string): string;
+/**
+ * The options schema of a settings section from its declaration: the file is imported in a child
+ * process in the project (its @dokebi/core), and core renders the schema. The text, as
+ * options.schema.json of plugins (two-space JSON, a final newline).
+ */
+export declare function renderSettingsSchema(root: string, section: string): Promise<string>;
+/** renderSettingsSchema from a declaration at `path` (a draft beside where it goes). */
+export declare function renderSettingsSchemaFrom(root: string, section: string, path: string): Promise<string>;
+/** The schema of a settings section from its schema file, or undefined when it is missing. */
+export declare function readSettingsSchema(root: string, section: string): Promise<Record<string, unknown> | undefined>;
+/**
+ * Sections of dokebi.yaml the framework names itself without a declaration: the cluster's process
+ * count (`application-runtime`, read by the generated main and by @dokebi/outbox) and the first
+ * admin a recipe writes (`first-admin`, older `blog-admin`). doctor does not report them.
+ */
+export declare const CONVENTION_SECTIONS: ReadonlySet<string>;
+/** Why a section of dokebi.yaml has no declaration: one code for config show/set/unset/secret. */
+export interface UndeclaredSection {
+    readonly code: 'UNKNOWN_PLUGIN' | 'UNDECLARED_SECTION';
+    readonly message: string;
+    readonly details: Record<string, unknown> & {
+        readonly fix: string;
+    };
+}
+/**
+ * D-0155: a section that no installed plugin, core section or settings section declares. A
+ * plugin id of the catalog (or `logging` without the logger) is a plugin that is not installed
+ * (UNKNOWN_PLUGIN, fix: add it); any other name is a section nobody declared
+ * (UNDECLARED_SECTION, fix: settings add). config set and secret refuse it (a value cannot be
+ * checked); config show and unset work on what is there and warn with the same code.
+ */
+export declare function undeclaredSection(section: string, packageOf: (id: string) => string | undefined, installed: readonly string[], settings: readonly string[]): UndeclaredSection;
+/** The refusal of config set or secret for an undeclared section, as a CLI error. */
+export declare function undeclaredSectionError(found: UndeclaredSection): CliError;
+/** The package of a catalog plugin id (`dokebi-redis` → `@dokebi/redis`), exact ids only. */
+export declare function catalogPackageOf(): Promise<(id: string) => string | undefined>;

package/dist/settings.js

@@ -0,0 +1,168 @@
+// D-0155: the settings of the application itself in their own section of dokebi.yaml,
+// `options.<section>`, declared in src/shared/settings/<section>.ts with core's defineSettings
+// (a defineOptions declaration). The CLI keeps the section's JSON Schema beside it,
+// src/shared/settings/<section>.schema.json, written from the declaration (`settings add` and
+// `settings sync` import the file in a child process; Node strips the types), so every command
+// reads it without a build: config show/set/unset/secret, doctor (which also says when the file
+// no longer matches the declaration), the example file and the reloadable marks treat the
+// section like a plugin's.
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+import { loadSchema } from '@dokebi/config';
+import { loadCatalog } from './catalog.js';
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+const exec = promisify(execFile);
+export const SETTINGS_FOLDER = 'src/shared/settings';
+/** Section names: as core's SETTINGS_SECTION (lower-case word, at most 64 characters). */
+export const SETTINGS_SECTION = /^[a-z][a-z0-9-]{0,63}$/;
+/** Core's own sections (options.logging, options.reload): never application settings. */
+export const RESERVED_SECTIONS = new Set(['logging', 'reload']);
+export const settingsFile = (section) => `${SETTINGS_FOLDER}/${section}.ts`;
+export const settingsSchemaFile = (section) => `${SETTINGS_FOLDER}/${section}.schema.json`;
+/** The camelCase name of the export a settings file default-exports (`survey-limits` → surveyLimits). */
+export function settingsIdentifier(section) {
+    return `${section.replace(/-([a-z0-9])/g, (_match, letter) => letter.toUpperCase())}Settings`;
+}
+/** The file `settings add` writes: one reloadable and one restart-only option to start from. */
+export function settingsSource(section) {
+    return `// The settings of this application in dokebi.yaml: options.${section} (D-0155). Every count,
+// size and time is an option with a minimum, a maximum and a default; reloadable ones apply while
+// the app runs (save dokebi.yaml, or npx dokebi reload), the others need a restart.
+// Read them where they are used: ${settingsIdentifier(section)}.read(context.app.config) (typed, cached per
+// configuration). After changing the declaration run npx dokebi settings sync (doctor says when).
+// Keep this file free of side effects: the CLI imports it to write ${section}.schema.json.
+import { defineOptions, defineSettings, option as o } from '@dokebi/core';
+
+export default defineSettings({
+  section: '${section}',
+  options: defineOptions({
+    pageSize: o.integer({
+      minimum: 1,
+      maximum: 1000,
+      default: 50,
+      reloadable: true,
+      description: 'Items per page of a list',
+    }),
+    workers: o.integer({
+      minimum: 1,
+      maximum: 64,
+      default: 2,
+      description: 'Background workers started with the app (a restart applies a change)',
+    }),
+  }),
+});
+`;
+}
+/**
+ * The options schema of a settings section from its declaration: the file is imported in a child
+ * process in the project (its @dokebi/core), and core renders the schema. The text, as
+ * options.schema.json of plugins (two-space JSON, a final newline).
+ */
+export async function renderSettingsSchema(root, section) {
+    return renderSettingsSchemaFrom(root, section, join(root, settingsFile(section)));
+}
+/** renderSettingsSchema from a declaration at `path` (a draft beside where it goes). */
+export async function renderSettingsSchemaFrom(root, section, path) {
+    const url = pathToFileURL(path).href;
+    const script = `
+const { renderOptionsSchema } = await import('@dokebi/core');
+const module = await import(${JSON.stringify(url)});
+const settings = module.default;
+if (!settings || settings.section !== ${JSON.stringify(section)} || !settings.options) {
+  process.stderr.write('The default export is not defineSettings({ section: ${JSON.stringify(section)}, options })\\n');
+  process.exit(3);
+}
+process.stdout.write(renderOptionsSchema(settings.options));
+`;
+    try {
+        const { stdout } = await exec(process.execPath, ['--input-type=module', '-e', script], {
+            cwd: root,
+            timeout: 30_000,
+            maxBuffer: 4 * 1024 * 1024,
+            env: { ...process.env, NODE_OPTIONS: '' },
+        });
+        debug('Settings schema rendered from its declaration', { section, bytes: stdout.length });
+        return stdout;
+    }
+    catch (cause) {
+        const stderr = String(cause.stderr ?? '').trim();
+        throw new CliError('SETTINGS_SCHEMA_FAILED', `The settings declaration ${settingsFile(section)} could not be read`, {
+            cause,
+            details: {
+                section,
+                file: settingsFile(section),
+                // The first lines of the error the import gave (code, not configuration values).
+                error: stderr.split('\n').slice(0, 20).join('\n'),
+                fix: `make ${settingsFile(section)} default-export defineSettings({ section: '${section}', options: defineOptions({...}) }) without side effects, then run npx dokebi settings sync`,
+            },
+        });
+    }
+}
+/** The schema of a settings section from its schema file, or undefined when it is missing. */
+export async function readSettingsSchema(root, section) {
+    const path = join(root, settingsSchemaFile(section));
+    try {
+        await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    return loadSchema(path);
+}
+/**
+ * Sections of dokebi.yaml the framework names itself without a declaration: the cluster's process
+ * count (`application-runtime`, read by the generated main and by @dokebi/outbox) and the first
+ * admin a recipe writes (`first-admin`, older `blog-admin`). doctor does not report them.
+ */
+export const CONVENTION_SECTIONS = new Set([
+    'application-runtime',
+    'first-admin',
+    'blog-admin',
+]);
+/**
+ * D-0155: a section that no installed plugin, core section or settings section declares. A
+ * plugin id of the catalog (or `logging` without the logger) is a plugin that is not installed
+ * (UNKNOWN_PLUGIN, fix: add it); any other name is a section nobody declared
+ * (UNDECLARED_SECTION, fix: settings add). config set and secret refuse it (a value cannot be
+ * checked); config show and unset work on what is there and warn with the same code.
+ */
+export function undeclaredSection(section, packageOf, installed, settings) {
+    const pkg = section === 'logging' ? '@dokebi/logger' : packageOf(section);
+    if (pkg !== undefined)
+        return {
+            code: 'UNKNOWN_PLUGIN',
+            message: `${section} is not installed`,
+            details: {
+                plugin: section,
+                package: pkg,
+                installed: [...installed],
+                settings: [...settings],
+                fix: `install it first: npx dokebi add ${pkg} (its options are then checked against its schema)`,
+            },
+        };
+    return {
+        code: 'UNDECLARED_SECTION',
+        message: `options.${section} is not declared: no installed plugin, core section or settings section of the application reads it`,
+        details: {
+            section,
+            installed: [...installed],
+            settings: [...settings],
+            fix: `declare it: npx dokebi settings add ${section} (it writes ${settingsFile(section)}, or adopts that file when it default-exports defineSettings({ section: '${section}', options })), then read it with ${settingsIdentifier(section)}.read(context.app.config); config set, unset, secret and show then check it like the options of a plugin`,
+        },
+    };
+}
+/** The refusal of config set or secret for an undeclared section, as a CLI error. */
+export function undeclaredSectionError(found) {
+    return new CliError(found.code, found.message, { details: found.details, phase: 'arguments' });
+}
+/** The package of a catalog plugin id (`dokebi-redis` → `@dokebi/redis`), exact ids only. */
+export async function catalogPackageOf() {
+    const catalog = await loadCatalog();
+    return (id) => catalog.packages.find((item) => item.id === id)?.package;
+}

package/dist/site-auth.d.ts

@@ -0,0 +1,39 @@
+/** The code the scaffold's stub hooks log (written by the site recipe since it exists). */
+export declare const SITE_AUTH_STUB_CODE = "SITE_AUTH_UNCONFIGURED";
+/** How long the whole probe may take (import, every hook); then the child is killed. */
+export declare const USER_STORE_PROBE_MS = 20000;
+/** What one hook did when the probe called it. */
+export interface HookProbe {
+    /**
+     * `stub`: the scaffold's deny stub; `app`: anything else (reads a store, finds someone, throws,
+     * takes time); `unimplemented`: the AuthExtension base answered EXTENSION_REQUIRED.
+     */
+    readonly state: 'stub' | 'app' | 'unimplemented';
+    /** How an `app` hook showed it: `dependency`, `found`, `none`, `threw`, `pending`. */
+    readonly how?: string;
+}
+/** One realm of the extension module. */
+export interface RealmProbe {
+    readonly realm: string;
+    /** False: the module exports no class for this realm. */
+    readonly defined: boolean;
+    /** Why the realm's class could not be made (its constructor threw). */
+    readonly failure?: string;
+    readonly findByIdentity?: HookProbe;
+    readonly findById?: HookProbe;
+}
+export type UserStoreProbe = {
+    readonly ok: true;
+    readonly realms: readonly RealmProbe[];
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** Runs in the project's folder (`node --input-type=module --eval`), like the describe runner. */
+export declare const USER_STORE_RUNNER: string;
+/**
+ * Probes the hooks of `realms` in the project's auth extension. Never throws: what went wrong is
+ * the result (`ok: false` with a code and a one-line reason) and a debug line with the error.
+ */
+export declare function probeUserStores(root: string, realms: readonly string[], timeoutMs?: number): Promise<UserStoreProbe>;

package/dist/site-auth.js

@@ -0,0 +1,195 @@
+// Whether the realms of a site still use the site scaffold's user-store stub (D-0137). The site
+// recipe writes src/infra/auth/extension.ts with findByIdentity and findById that find nobody
+// (every login is denied) and log the code SITE_AUTH_UNCONFIGURED; the builder connects a realm
+// by writing those hooks against its user store. AI-M27: verify kept telling the user "the
+// generated auth extensions deny every login" after the builder had connected them, because the
+// sentence was fixed text.
+//
+// How it is told: by the hooks' behaviour, not by their text. A child process in the project's
+// folder imports the extension module (nothing else of the app: no plugin is set up, nothing
+// listens or connects) and calls each hook of each realm once with a probe identity and a hook
+// context whose getDependency throws (no store can be reached) and whose logger records the codes
+// it is given. A hook is the stub only when it answers undefined, logs SITE_AUTH_UNCONFIGURED and
+// asks for no dependency: an edited hook that reads a store asks for its dependency, finds
+// someone, throws or takes time, and is app code. Projects of every site recipe so far carry the
+// same stub (one version since the recipe exists), so they are told the same way.
+import { spawn } from 'node:child_process';
+import { debug, describeError, maskTexts } from './diagnostics.js';
+import { appEnvironment } from './env-file.js';
+import { exists, securePath } from './filesystem.js';
+import { EXTENSION_FILE } from './recipe-login.js';
+/** The code the scaffold's stub hooks log (written by the site recipe since it exists). */
+export const SITE_AUTH_STUB_CODE = 'SITE_AUTH_UNCONFIGURED';
+/** How long the whole probe may take (import, every hook); then the child is killed. */
+export const USER_STORE_PROBE_MS = 20_000;
+/** How long one hook may take before the probe counts it as app code (the stub answers at once). */
+const HOOK_MS = 2_000;
+/** How long the child may take to exit once it answered. */
+const EXIT_GRACE_MS = 2_000;
+/** Runs in the project's folder (`node --input-type=module --eval`), like the describe runner. */
+export const USER_STORE_RUNNER = `import { pathToFileURL } from 'node:url';
+const base = pathToFileURL(process.cwd() + '/');
+const STUB = ${JSON.stringify(SITE_AUTH_STUB_CODE)};
+const HOOK_MS = ${HOOK_MS};
+const PENDING = Symbol('pending');
+const reason = (error) => {
+  let text;
+  try { text = error instanceof Error ? error.message : String(error); } catch (failure) { text = typeof error + ' (' + typeof failure + ')'; }
+  return (String(text).split('\\n', 1)[0] || 'Unknown error').replace(/\\/\\/[^\\s/]*@/g, '//***@').slice(0, 300);
+};
+const answer = (message) => new Promise((resolve) => process.send(message, () => resolve(undefined)));
+const noDependency = Object.assign(new Error('The CLI user-store probe gives no dependency'), { code: 'CLI_PROBE' });
+async function hook(instance, name, realm) {
+  const codes = [];
+  let dependency = false;
+  const logger = {
+    isEnabled: () => true,
+    log: (_level, _message, fields) => { if (fields && typeof fields.code === 'string') codes.push(fields.code); },
+  };
+  logger.child = () => logger;
+  const controller = new AbortController();
+  const context = Object.freeze({
+    realm,
+    app: Object.freeze({}),
+    logger,
+    signal: controller.signal,
+    getDependency() { dependency = true; throw noDependency; },
+  });
+  let timer;
+  try {
+    const input = name === 'findById' ? 'dokebi-cli-probe' : 'dokebi-cli-probe@example.invalid';
+    const value = await Promise.race([
+      Promise.resolve().then(() => instance[name](input, context)),
+      new Promise((resolve) => { timer = setTimeout(() => resolve(PENDING), HOOK_MS); }),
+    ]);
+    if (value === PENDING) return { state: 'app', how: 'pending' };
+    if (value === undefined && !dependency && codes.includes(STUB)) return { state: 'stub' };
+    return { state: 'app', how: dependency ? 'dependency' : value === undefined ? 'none' : 'found' };
+  } catch (error) {
+    if (error?.code === 'EXTENSION_REQUIRED') return { state: 'unimplemented' };
+    return { state: 'app', how: dependency ? 'dependency' : 'threw' };
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+}
+try {
+  const realms = JSON.parse(process.env.DOKEBI_CLI_PROBE_REALMS || '[]');
+  const module = await import(new URL(${JSON.stringify(EXTENSION_FILE)}, base).href);
+  const classes = new Map();
+  if (typeof module.default === 'function') classes.set('default', module.default);
+  if (module.realms && typeof module.realms === 'object')
+    for (const [name, value] of Object.entries(module.realms)) if (typeof value === 'function') classes.set(name, value);
+  const found = [];
+  for (const realm of realms) {
+    const Realm = classes.get(realm);
+    if (!Realm) { found.push({ realm, defined: false }); continue; }
+    let instance;
+    try { instance = new Realm(); } catch (error) { found.push({ realm, defined: true, failure: reason(error) }); continue; }
+    found.push({ realm, defined: true, findByIdentity: await hook(instance, 'findByIdentity', realm), findById: await hook(instance, 'findById', realm) });
+  }
+  await answer({ type: 'stores', realms: found });
+} catch (error) {
+  await answer({ type: 'failure', code: typeof error?.code === 'string' ? error.code : 'EXTENSION_UNREADABLE', message: reason(error) });
+  process.exitCode = 1;
+}
+process.disconnect();
+`;
+/**
+ * Probes the hooks of `realms` in the project's auth extension. Never throws: what went wrong is
+ * the result (`ok: false` with a code and a one-line reason) and a debug line with the error.
+ */
+export async function probeUserStores(root, realms, timeoutMs = USER_STORE_PROBE_MS) {
+    const started = performance.now();
+    try {
+        if (!(await exists(await securePath(root, EXTENSION_FILE))))
+            return { ok: false, code: 'EXTENSION_MISSING', message: `${EXTENSION_FILE} does not exist` };
+    }
+    catch (error) {
+        debug('User-store probe: the extension path could not be checked', {
+            error: describeError(error),
+        });
+        return {
+            ok: false,
+            code: 'EXTENSION_UNREADABLE',
+            message: `${EXTENSION_FILE} could not be read`,
+        };
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, ['--input-type=module', '--disable-warning=ExperimentalWarning', '--eval', USER_STORE_RUNNER], {
+            cwd: root,
+            // The project's .env under the CLI's environment, like dokebi start and describe.
+            env: {
+                ...appEnvironment(root, 'production'),
+                DOKEBI_CLI_PROBE_REALMS: JSON.stringify(realms),
+            },
+            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+        });
+    }
+    catch (error) {
+        debug('User-store probe: the child process did not start', { error: describeError(error) });
+        return { ok: false, code: 'PROBE_FAILED', message: 'the probe process did not start' };
+    }
+    // The module's own output: kept (bounded) for the debug line, never printed.
+    let output = '';
+    const keep = (chunk) => {
+        output = (output + chunk.toString('utf8')).slice(-4_096);
+    };
+    child.stdout?.on('data', keep);
+    child.stderr?.on('data', keep);
+    const result = await new Promise((resolve) => {
+        let message;
+        let grace;
+        const timer = setTimeout(() => {
+            debug('User-store probe: time limit reached; killing it', { timeoutMs });
+            child.kill('SIGKILL');
+            resolve({
+                ok: false,
+                code: 'PROBE_TIMEOUT',
+                message: `importing ${EXTENSION_FILE} and calling its hooks took more than ${timeoutMs} ms`,
+            });
+        }, timeoutMs);
+        child.on('message', (received) => {
+            message = maskTexts(received);
+            grace = setTimeout(() => child.kill('SIGKILL'), EXIT_GRACE_MS);
+        });
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            if (grace)
+                clearTimeout(grace);
+            debug('User-store probe: the child process failed', { error: describeError(error) });
+            resolve({ ok: false, code: 'PROBE_FAILED', message: error.message });
+        });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timer);
+            if (grace)
+                clearTimeout(grace);
+            if (message?.type === 'stores')
+                resolve({ ok: true, realms: message.realms });
+            else if (message?.type === 'failure')
+                resolve({ ok: false, code: message.code, message: message.message });
+            else
+                resolve({
+                    ok: false,
+                    code: 'PROBE_FAILED',
+                    message: `the probe process exited (${code ?? signal}) before it answered`,
+                });
+        });
+    });
+    debug('User-store probe finished', {
+        ok: result.ok,
+        ...(result.ok
+            ? {
+                realms: result.realms.map((item) => ({
+                    realm: item.realm,
+                    defined: item.defined,
+                    findByIdentity: item.findByIdentity?.state ?? null,
+                    findById: item.findById?.state ?? null,
+                })),
+            }
+            : { code: result.code, reason: result.message, output }),
+        ms: Math.round(performance.now() - started),
+    });
+    return result;
+}

package/dist/template-fixes.d.ts

@@ -0,0 +1,26 @@
+import type { Diagnostic } from './project-inspector.js';
+interface TemplateFix {
+    readonly id: string;
+    readonly marker: RegExp;
+    /** What the fix does and the change that brings it over. */
+    readonly what: string;
+}
+/** The fixes of each @dokebi/db adapter template (`templates/adapters/<id>.ts`). */
+export declare const ADAPTER_FIXES: Readonly<Record<string, readonly TemplateFix[]>>;
+export interface TemplateSources {
+    /** The installed @dokebi/db package name, whose `templates/adapters` the copies came from. */
+    readonly db?: string | undefined;
+    /** The installed apps host (D-0070), whose `templates/inertia-build` the Vite configs came from. */
+    readonly apps?: {
+        readonly id: string;
+        readonly packageName: string;
+    } | undefined;
+    /** @dokebi/template-inertia is installed: it serves the build the Vite configs write. */
+    readonly inertia: boolean;
+}
+/**
+ * TEMPLATE_FIX_MISSING warnings for the copies under `root`. Templates resolve from `base`
+ * (the project, or upgrade's staging install) like Node in a workspace member (D-0035).
+ */
+export declare function templateFixes(root: string, base: string, sources: TemplateSources): Promise<Diagnostic[]>;
+export {};