@dokebi/cli 0.4.2 → 0.4.26

package/dist/project-state.js

@@ -103,6 +103,13 @@ export function readState(value) {
                 throw new CliError('INVALID_STATE', 'Invalid module name');
         });
     }
+    let settings;
+    if (input.settings !== undefined) {
+        settings = stringList(input.settings, (name) => {
+            if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) || name === 'logging' || name === 'reload')
+                throw new CliError('INVALID_STATE', 'Invalid settings section');
+        });
+    }
     return {
         schemaVersion: 2,
         plugins,
@@ -111,6 +118,7 @@ export function readState(value) {
         generatedHash: input.generatedHash,
         ...(apps?.length ? { apps } : {}),
         ...(modules?.length ? { modules } : {}),
+        ...(settings?.length ? { settings } : {}),
     };
 }
 export function readConfig(value) {

package/dist/project.d.ts

@@ -1,6 +1,10 @@
+import { type ConfigDiffResult } from './config-diff.js';
 import { type SetOption, type Warning } from './config-edit.js';
+import { type OptionPaths } from './config-paths.js';
+import { ENV_FILE } from './dev-infra.js';
 import { NpmClient } from './npm-client.js';
 import { type Resolution } from './registry.js';
+import { type AppView } from './view-choice.js';
 export interface ConfigRequirement {
     plugin: string;
     errors: Array<{
@@ -11,12 +15,24 @@ export interface ConfigRequirement {
 }
 export interface PreservedDetail {
     path: string;
-    reason: 'MODIFIED' | 'DELETED' | 'SHARED';
+    reason: 'MODIFIED' | 'DELETED' | 'SHARED' | 'RETIRED_USER_FILE';
     update?: string;
 }
 export interface OperationResult {
     changed: string[];
     preserved: string[];
+    /** config set, unset, secret and diff --write: the option paths each file lost, changed or gained. */
+    paths?: Record<string, OptionPaths>;
+    /** D-0098: the EJS app `add` created with the apps host (`main`), whose view the CLI records. */
+    firstApp?: string;
+    /**
+     * `app add`: the view the app got (`ejs`, `none`, `inertia-vue`, `inertia-vue-ssr`) and where
+     * it came from: `recipe` when the project's recipe built no screens and no flag chose the view.
+     */
+    appView?: {
+        value: string;
+        from: 'flags' | 'recipe';
+    };
     preservedDetails?: PreservedDetail[];
     configRequired?: ConfigRequirement[];
     /** Required plugins installed together with the requested one (manifest `package`). */
@@ -25,8 +41,12 @@ export interface OperationResult {
         packageName: string;
         version: string;
     }>;
+    /** `deprecated`: an install plan field this CLI still takes but a later one drops. */
     warnings?: Array<Warning & {
         plugin?: string;
+        deprecated?: string;
+        hint?: string;
+        count?: number;
     }>;
     /** What to do after this command: a command (or an edit) and why (D-0065). */
     nextSteps?: NextStep[];
@@ -34,26 +54,53 @@ export interface OperationResult {
     resolved?: Resolution;
     from?: string;
     to?: string;
-    /** Why an upgrade to the same version was applied: the installed manifest differs (D-0037). */
-    reason?: 'MANIFEST_CHANGED';
+    /**
+     * Why an upgrade to the same version was applied: the installed manifest differs (D-0037), or
+     * the package's content does (an unpublished version rebuilt and given as `--to <tgz>`).
+     */
+    reason?: 'MANIFEST_CHANGED' | 'PACKAGE_CHANGED';
     /** npm workspace root where `npm install` ran (or, in a dry run, would run) (D-0035). */
     workspaceInstall?: string;
     /**
-     * Secrets `add` generated into .env for the plugins it installed (D-0073): variable names only,
-     * the values are never shown. A variable already set in the environment or .env is kept.
+     * Secrets `add` generated for the plugins it installed (D-0073 addendum 2): the option in
+     * dokebi.yaml (`configSecrets`), or a variable in .env for a plugin that still declares the
+     * deprecated `envSecrets`. Names only, the values are never shown; an existing value is kept.
      */
     generatedSecrets?: GeneratedSecret[];
 }
-/** One generated secret of `add` (D-0073). */
-export interface GeneratedSecret {
-    readonly variable: string;
+/** One generated secret of `add`: an option in dokebi.yaml, or (deprecated) a .env variable. */
+export type GeneratedSecret = {
+    readonly plugin: string;
+    readonly option: string;
     readonly file: string;
+} | {
     readonly plugin: string;
+    readonly variable: string;
+    readonly file: typeof ENV_FILE;
+};
+export declare const ROTATE_KEEP = 2;
+/** What `config secret` did at one option: names and counts only, never a value. */
+export interface SecretOutcome {
+    readonly path: string;
+    readonly list: boolean;
+    readonly generated: boolean;
+    /** The value came from stdin (`--stdin`), not generated. */
+    readonly stdin?: boolean;
+    /** `--rotate` replaced an existing value. */
+    readonly rotated?: boolean;
+    /** Previous secrets kept after the new one (a list), and older ones dropped. */
+    readonly kept?: number;
+    readonly dropped?: number;
 }
 /** `dokebi add` choices beyond the package (D-0065). */
 export interface AddOptions {
     /** @dokebi/db: write this adapter (pg, mysql2, mariadb, mongodb), its connection and driver. */
     adapter?: string;
+    /**
+     * @dokebi/db with `adapter` (D-0127): written as connections.main.startup only when given;
+     * `optional` lets the app start and run while that database is down.
+     */
+    startup?: 'required' | 'optional';
     /** The plugin that hosts apps (D-0070): false skips the first `main` app (`--no-first-app`). */
     firstApp?: boolean;
 }
@@ -65,6 +112,9 @@ export interface NextStep {
 /** `dokebi init`: the created folder, plus what to do next (machine-readable). */
 export interface InitResult extends OperationResult {
     nextSteps: NextStep[];
+    deployment?: {
+        files: string[];
+    };
 }
 /**
  * Follow-ups after init (D-0065): read the guide, pick a recipe and ask its questions, find
@@ -87,15 +137,25 @@ staging?: string): Promise<{
     exists: boolean;
     kept: string[];
 }>;
+/** D-0151: the app logger every new project gets. */
+export declare const LOGGER_PACKAGE = "@dokebi/logger";
 export declare class Project {
     #private;
     private readonly npm;
     constructor(npm?: NpmClient);
-    init(target: string, core?: string, dryRun?: boolean): Promise<InitResult>;
+    /**
+     * A new project (D-0065). D-0151: every new project gets @dokebi/logger, added by `add` once
+     * the project exists (stdout JSON, pretty output in dokebi dev, a file target to turn on for
+     * production). When that install fails (offline, a registry without it) the project stays on
+     * core's console logger and the result says so (warning LOGGER_NOT_INSTALLED and the command).
+     */
+    init(target: string, core?: string, dryRun?: boolean, deploy?: boolean, logger?: boolean): Promise<InitResult>;
     migrate(root: string, dryRun?: boolean): Promise<OperationResult>;
     add(root: string, spec: string, dryRun?: boolean, sets?: readonly SetOption[], options?: AddOptions): Promise<OperationResult>;
     remove(root: string, id: string, dryRun?: boolean): Promise<OperationResult>;
     upgrade(root: string, id: string, to?: string, dryRun?: boolean): Promise<OperationResult>;
+    /** Refresh only maintained AGENTS blocks; project instructions remain byte-for-byte intact. */
+    syncGuide(root: string, dryRun?: boolean): Promise<OperationResult>;
     /**
      * `dokebi config set <plugin>.<path>=<value>…`: non-secret options in dokebi.yaml, checked
      * against that plugin's schema (only missing required values are tolerated and reported).
@@ -103,11 +163,47 @@ export declare class Project {
     configSet(root: string, assignments: readonly {
         plugin: string;
         set: SetOption;
-    }[], dryRun?: boolean): Promise<OperationResult>;
+    }[], dryRun?: boolean): Promise<OperationResult & {
+        file: string;
+    }>;
+    /**
+     * `dokebi config unset <plugin>.<path>…` (D-0153): removes options from dokebi.yaml, and from
+     * dokebi.example.yaml where the sample has them, in one transaction. A path that is not set is
+     * a warning (OPTION_NOT_SET), not an error, so a repeated call changes nothing. Values are never
+     * returned or logged; removing a secret is allowed and warned (SECRET_REMOVED: what it signed
+     * no longer verifies). The plugin need not be installed (a section kept by `dokebi remove`).
+     * Removing may only leave issues the options already had, or missing required values
+     * (configRequired); issues that remain are a warning that carries the next fix.
+     */
+    configUnset(root: string, targets: readonly {
+        plugin: string;
+        path: readonly string[];
+    }[], dryRun?: boolean): Promise<OperationResult & {
+        file: string;
+        removed: {
+            option: string;
+            files: string[];
+        }[];
+    }>;
     /**
-     * `dokebi dev-infra` (D-0065): compose.yaml for the database of connection `main`, a generated
-     * password in .env (git-ignored) and the matching URL in dokebi.yaml. An existing compose.yaml
-     * with a `db` service and an existing password are kept; nothing is started here.
+     * `dokebi config diff [<id>] --write` (AI-M46): copies the options only in dokebi.yaml into
+     * dokebi.example.yaml without their secrets, in one transaction. Paths both files set keep the
+     * sample's value (a sample may differ) unless `values` (`--values`, Studio v2) writes
+     * dokebi.yaml's; secrets inside a copied path are left out. The written sample is compared
+     * again and refused if it would hold a secret (fail closed).
+     */
+    configSample(root: string, section: string | undefined, dryRun?: boolean, prune?: boolean, values?: boolean): Promise<OperationResult & {
+        file: string;
+        written: string[];
+        pruned: string[];
+        valuesWritten?: string[];
+        diff: ConfigDiffResult;
+    }>;
+    /**
+     * `dokebi dev-infra` (D-0065): compose.yaml for the database of connection `main` and the URL
+     * with a generated password in dokebi.yaml (no .env is written; a legacy .env password is reused
+     * only when the YAML has no URL). An existing compose.yaml with a `db` service and an existing
+     * password are kept; nothing is started here.
      */
     devInfra(root: string, options?: {
         dbPort?: number;
@@ -118,14 +214,59 @@ export declare class Project {
     /**
      * `dokebi config secret <plugin>.<path>`: a generated random secret (32 bytes, base64url) in
      * dokebi.yaml, as a one-item list when the schema wants a list. The value is never returned or
-     * logged; an existing value is kept (SECRET_KEPT). Secrets never pass the command line.
+     * logged; an existing value is kept (SECRET_KEPT) unless `rotate` (`--rotate`, AI-M05): a string
+     * is replaced; a list gets the new secret first (it signs) and keeps the previous ones after it,
+     * at most ROTATE_KEEP of them (older ones are dropped: SECRETS_DROPPED), so what the old ones
+     * signed still verifies during the rotation. Secrets never pass the command line. `value`
+     * (`--stdin`, D-0151 follow-up): a secret someone else issued, such as the token of a log
+     * receiver (`logging.targets.studio.token`), written instead of a generated one; never returned
+     * or logged either. A list item is named by its `name` (else `type`) or its index.
      */
-    configSecret(root: string, id: string, path: readonly string[], dryRun?: boolean): Promise<OperationResult & {
-        secret: {
-            path: string;
-            list: boolean;
-            generated: boolean;
+    configSecret(root: string, id: string, path: readonly string[], dryRun?: boolean, rotate?: boolean, value?: string): Promise<OperationResult & {
+        file: string;
+        secret: SecretOutcome;
+    }>;
+    /**
+     * `dokebi config init` (D-0163, R3 Claude T4 review): a fresh copy of a project (a clone, a CI
+     * checkout) has no dokebi.yaml, which stays out of version control, and no command made one:
+     * `dev-infra up` failed with INTERNAL_ERROR. Writes it from dokebi.example.yaml with a generated
+     * secret for every required secret option the sample leaves out (the sample holds none), and
+     * names the placeholders (`<set … here>`) still to fill. Never replaces an existing file.
+     */
+    configInit(root: string, dryRun?: boolean): Promise<OperationResult & {
+        file: string;
+        generatedSecrets: GeneratedSecret[];
+        placeholders: string[];
+    }>;
+    /**
+     * User code a recipe writes (D-0076 §6, `recipe blog --admin login`), in one transaction under
+     * the project lock. A new file is written; a file with the same content is left alone; a file
+     * marked `replaceTemplate` is replaced only while it still is the untouched template its plugin
+     * installed (the hash `state.files` recorded); anything else is RECIPE_FILE_CONFLICT. `edits`
+     * change existing files (they return the text unchanged when already applied). `config` sets
+     * values of a dokebi.yaml section no plugin owns; a `secret` value is generated (never returned
+     * or logged) and an existing one is kept. Nothing is written when nothing changes.
+     */
+    writeRecipeFiles(root: string, request: {
+        readonly files: readonly {
+            readonly path: string;
+            readonly content: string;
+            readonly replaceTemplate?: boolean;
+        }[];
+        readonly edits?: readonly {
+            readonly path: string;
+            edit(text: string): string;
+        }[];
+        readonly config?: {
+            readonly section: string;
+            readonly values: readonly {
+                readonly key: string;
+                readonly value?: string;
+            }[];
         };
+    }): Promise<OperationResult & {
+        written: string[];
+        kept: string[];
     }>;
     private coreVersion;
     /**
@@ -139,11 +280,19 @@ export declare class Project {
         inertia?: boolean;
         /** With `inertia`: render the first HTML of a page on the server (D-0039). */
         ssr?: boolean;
+        /** Seal these domains (`domains.<host>.seal: true`, @dokebi/seal, D-0062/D-0092). */
+        seal?: boolean;
+        /**
+         * `ejs` or `none` (no views, a JSON API). Unset: `none` when the project's recipe built no
+         * browser screens (the api recipe records view = none, D-0098), else `ejs`.
+         */
+        view?: AppView;
     }): Promise<OperationResult>;
     /** `dokebi app link <app> <domain> [--template t]`: maps one more domain to an existing app. */
     appLink(root: string, name: string, domain: string, options?: {
         template?: string;
         dryRun?: boolean;
+        seal?: boolean;
     }): Promise<OperationResult>;
     /** `dokebi app unlink <domain>`: removes one domain mapping from dokebi.yaml and the sample. */
     appUnlink(root: string, domain: string, dryRun?: boolean): Promise<OperationResult>;
@@ -177,5 +326,40 @@ export declare class Project {
             path: string;
         }[];
     }>;
+    /**
+     * D-0155: `dokebi settings add <section>`: the settings of the application in options.<section>.
+     * Writes src/shared/settings/<section>.ts (or keeps one that is already there and default-exports
+     * defineSettings for this section), its schema file from the declaration, the defaults of the
+     * section in dokebi.yaml and the example (with the reloadable marks), and registers it so the
+     * app checks the section at start. A plugin's section, logging or reload is refused.
+     */
+    settingsAdd(root: string, section: string, options?: {
+        dryRun?: boolean;
+    }): Promise<OperationResult>;
+    /**
+     * D-0155: `dokebi settings sync`: writes the schema file of every settings section again from
+     * its declaration and adds the defaults of new options to dokebi.yaml and the example (with the
+     * reloadable marks). Nothing is written when every schema is current. AI-M49 D2: a value that
+     * is still the old default (the CLI wrote it) follows a changed default (`followed`), and the
+     * options are checked against the new schema as doctor checks them: a missing required value
+     * is `configRequired`, anything else INVALID_PLUGIN_OPTIONS and nothing is written.
+     */
+    settingsSync(root: string, dryRun?: boolean): Promise<OperationResult & {
+        sections: {
+            section: string;
+            changed: boolean;
+            followed?: string[];
+        }[];
+    }>;
+    /** `dokebi settings remove <section>`: unregisters it; its files and its options stay. */
+    settingsRemove(root: string, section: string, dryRun?: boolean): Promise<OperationResult>;
+    /** `dokebi settings list`: the settings sections with their declaration and schema files. */
+    settingsList(root: string): Promise<{
+        settings: {
+            section: string;
+            file: string;
+            schema: string;
+        }[];
+    }>;
     private writeConfiguration;
 }