@dokebi/cli 0.4.1 → 0.4.26

package/dist/recipe-facts.d.ts

@@ -0,0 +1,127 @@
+import type { FirstAdmin } from './first-admin.js';
+import type { UserStoreProbe } from './site-auth.js';
+/** What a fact notice is about; its arguments are words without spaces (domains, a mode). */
+export type Fact = {
+    readonly id: 'site';
+} | {
+    readonly id: 'csrf';
+    readonly mode: CsrfMode;
+} | {
+    readonly id: 'seal';
+    readonly view: 'ejs' | 'inertia';
+    readonly domains: readonly string[];
+} | {
+    readonly id: 'ssr-seal';
+    readonly domains: readonly string[];
+} | {
+    readonly id: 'mail';
+} | {
+    readonly id: 'session';
+};
+/**
+ * The CSRF notice of a plan: `inertia` and `form-body` (EJS forms) for the blog, `site-api`
+ * (application API calls), `site-inertia` and `site-ejs` (the site's browser apps).
+ */
+export type CsrfMode = 'inertia' | 'form-body' | 'site-api' | 'site-inertia' | 'site-ejs';
+/** The recorded form of a fact notice. */
+export declare function factToken(fact: Fact): string;
+/** The fact of a recorded token; undefined for any other notice (or a token this CLI does not know). */
+export declare function parseFact(notice: string): Fact | undefined;
+/**
+ * How the forms of a plan send the CSRF token (D-0076 §6): @dokebi/csrf is installed for every
+ * write form, so the report says what each view does instead of "no CSRF protection".
+ */
+export declare function csrfNotice(inertia: boolean): string;
+/** The seal head an EJS layout writes in its `<head>` (the shipped template-ejs layout's words). */
+export declare const SEAL_HEAD = "<%- data.seal?.head ?? '' %>";
+/**
+ * The browser module the generated Inertia entry (`views/app.js`) imports on sealed pages: it
+ * imports `@dokebi/seal/http`, which `dokebiInertia()` of the generated vite.config.ts maps to this
+ * served file (D-0062 addendum 2026-10-20).
+ */
+export declare const SEAL_HTTP_MODULE = "/dokebi/seal/http.mjs";
+/**
+ * What the user must know about the sealed browser hosts of a plan (D-0092 §1, D-0062): the
+ * consumer convention seals every browser app. EJS forms keep working without per-form code;
+ * Inertia pages and visits go sealed through the bootstrap of the generated entry.
+ */
+export declare function sealNotice(domains: readonly string[], view?: 'ejs' | 'inertia'): string;
+/**
+ * Why the browser hosts of a server-rendered Inertia plan stay unsealed (D-0062 §5): SSR writes
+ * the page props into the first HTML as plain text, so @dokebi/template-inertia refuses to start
+ * an SSR scope on a seal host (SEAL_SSR_CONFLICT). The user chose SSR; the convention still asks
+ * for Seal, so the user decides between the two.
+ */
+export declare function ssrSealNotice(domains: readonly string[]): string;
+/**
+ * Which hosts gain from seal (the @dokebi/seal guide, audit 2026-10-25): a host that only shows
+ * public pages needs no seal, so SSR there is no conflict to ask the user about.
+ */
+export declare const READ_ONLY_HOSTS = "Seal a host whose pages send data (forms, sealedFetch, Inertia visits). A host that only shows public pages (no writes, no signed-in JSON) gains nothing from seal: leave its domain without `seal: true`. Its pages then need no seal files and no 'wasm-unsafe-eval', and may use Inertia SSR.";
+/** What @dokebi/session would add to an EJS blog without it (AI-M05 F3). */
+export declare const SESSION_OFFER = "npx dokebi add @dokebi/session makes a refused form go back to its page with the typed values and the field messages";
+/** The notice of an EJS plan without @dokebi/session (AI-M05 F3: not installed behind the user's back). */
+export declare const SESSION_NOTICE = "Without @dokebi/session (not part of these choices), a form with invalid input shows an error page instead of coming back with what was typed; say if you want it added (npx dokebi add @dokebi/session).";
+/** The parts of the site plan the planned site notice names (siteDefinition). */
+export interface PlannedSite {
+    readonly apps: readonly string[];
+    readonly realms: Readonly<Record<string, string>>;
+    readonly worker: string;
+}
+/** What the plan does, for the recipe's report. */
+export interface PlanFacts {
+    readonly recipe: string;
+    readonly site?: PlannedSite;
+    /** The login name of the first admin the plan writes (or keeps), when it has an admin login. */
+    readonly adminLogin?: string;
+}
+/** The notice of a fact as the plan makes it (the recipe's report). */
+export declare function plannedText(fact: Fact, plan: PlanFacts): string;
+/** What verify read from the project for the fact notices. */
+export interface ProjectFacts {
+    readonly root: string;
+    /** The ids of the installed plugins (.dokebi/state.json). */
+    readonly installed: ReadonlySet<string>;
+    readonly options: Record<string, unknown>;
+    /** The id of the plugin that hosts apps (`dokebi-app`), when one is installed. */
+    readonly appsHost?: string;
+    /** The app verify started was ready: every plugin set up, every job queue bound. */
+    readonly started: boolean;
+    readonly firstAdmin: () => Promise<FirstAdmin>;
+    readonly userStores: (realms: readonly string[]) => Promise<UserStoreProbe>;
+    /**
+     * The settings file `options` was read from, as the CLI names it (M50: the one DOKEBI_CONFIG
+     * names, else dokebi.yaml, the default when left out); the notices name it.
+     */
+    readonly settingsFile?: string;
+}
+/**
+ * Reads the installed plugins and the settings file (DOKEBI_CONFIG, else dokebi.yaml) for `projectText`; undefined (and a debug line with
+ * the error) when either cannot be read, and the notices then say the CLI could not read them.
+ */
+export declare function readProjectFacts(root: string, input: Pick<ProjectFacts, 'started' | 'firstAdmin' | 'userStores'>): Promise<ProjectFacts | undefined>;
+/** The notice of a fact when the project could not be read: that, and where to look. */
+export declare function unreadText(fact: Fact, recipe: string): string;
+/** The notice of a fact as the project is now; '' when nothing is left to say (the line is dropped). */
+export declare function projectText(fact: Fact, entry: {
+    readonly recipe: string;
+    readonly answers: Readonly<Record<string, {
+        value: string;
+    }>>;
+}, facts: ProjectFacts): Promise<string>;
+/** What the probe of the realms' hooks found (site-auth.ts), in words. */
+export declare function userStoreText(probe: UserStoreProbe): string;
+/** The fact of a notice a record before D-0137 holds as a sentence; undefined for any other. */
+export declare function recordedFact(notice: string): Fact | undefined;
+/** The fact of a recorded notice: a token, or an old sentence; undefined for any other notice. */
+export declare function factOf(notice: string): Fact | undefined;
+/** The key of a fact notice of a recipe in the map verify fills (`factTexts`). */
+export declare function factKey(recipe: string, fact: Fact): string;
+/** Every fact notice of the recipes as the project is now (verify), by `factKey`. */
+export declare function factTexts(recipes: readonly {
+    readonly recipe: string;
+    readonly notices: readonly string[];
+    readonly answers: Readonly<Record<string, {
+        value: string;
+    }>>;
+}[], facts: ProjectFacts | undefined): Promise<Map<string, string>>;