@dokebi/cli 0.2.4 → 0.4.0

package/dist/project-state.d.ts

@@ -1,7 +1,14 @@
+import { type FileOwner } from './install-plan.js';
 import { type PluginManifest } from './manifest.js';
 export interface OwnedFile {
     hash: string;
+    /** The plugins that installed the file (ids). */
     owners: string[];
+    /**
+     * Who edits it (D-0065 §11): `user` (a scaffold to change; doctor stays silent) or `cli`
+     * (regenerated; an edit is MODIFIED_TEMPLATE). States written before this field read as `user`.
+     */
+    owner: FileOwner;
 }
 /** Per-plugin results of the install lifecycle that are not part of the package manifest. */
 export interface Installation {
@@ -15,9 +22,13 @@ export interface ProjectState {
     installations: Record<string, Installation>;
     files: Record<string, OwnedFile>;
     generatedHash: string;
-    /** Apps of @dokebi/app in registration order (src/apps/<name>/app.ts), D-0030. */
+    /**
+     * Apps in registration order (src/apps/<name>/app.ts), D-0030, for the plugin that hosts apps
+     * (D-0070). That a host is installed is checked where the apps are used (generation, app
+     * commands): a state written before the manifests declared roles still loads, so upgrade works.
+     */
     apps?: string[];
-    /** Modules of @dokebi/module in registration order (src/shared/modules/<name>), D-0032. */
+    /** Modules in registration order (src/shared/modules/<name>), D-0032, for the modules host. */
     modules?: string[];
 }
 /** App and template names: lower-case letters, digits and hyphens, starting with a letter. */

package/dist/project-state.js

@@ -1,5 +1,6 @@
 import { CliError } from './errors.js';
 import { object, templateTarget } from './filesystem.js';
+import { FILE_OWNERS } from './install-plan.js';
 import { ID, readStoredManifest } from './manifest.js';
 /** App and template names: lower-case letters, digits and hyphens, starting with a letter. */
 export const APP_NAME = /^[a-z][a-z0-9-]{0,31}$/;
@@ -47,9 +48,14 @@ export function readState(value) {
             !Array.isArray(file.owners) ||
             !file.owners.length ||
             !file.owners.every((owner) => typeof owner === 'string' && plugins.some((plugin) => plugin.id === owner)) ||
-            new Set(file.owners).size !== file.owners.length)
+            new Set(file.owners).size !== file.owners.length ||
+            (file.owner !== undefined && !FILE_OWNERS.includes(file.owner)))
             throw new CliError('INVALID_STATE', 'Invalid file ownership');
-        files[path] = { hash: file.hash, owners: file.owners };
+        files[path] = {
+            hash: file.hash,
+            owners: file.owners,
+            owner: file.owner === undefined ? 'user' : file.owner,
+        };
     }
     const installations = Object.create(null);
     if (input.schemaVersion === 1) {
@@ -89,8 +95,6 @@ export function readState(value) {
             if (!APP_NAME.test(name))
                 throw new CliError('INVALID_STATE', 'Invalid app name');
         });
-        if (apps.length && !plugins.some((plugin) => plugin.id === 'dokebi-app'))
-            throw new CliError('INVALID_STATE', 'Apps need the dokebi-app plugin');
     }
     let modules;
     if (input.modules !== undefined) {
@@ -98,8 +102,6 @@ export function readState(value) {
             if (!APP_NAME.test(name))
                 throw new CliError('INVALID_STATE', 'Invalid module name');
         });
-        if (modules.length && !plugins.some((plugin) => plugin.id === 'dokebi-module'))
-            throw new CliError('INVALID_STATE', 'Modules need the dokebi-module plugin');
     }
     return {
         schemaVersion: 2,

package/dist/project.d.ts

@@ -1,5 +1,6 @@
 import { type SetOption, type Warning } from './config-edit.js';
 import { NpmClient } from './npm-client.js';
+import { type Resolution } from './registry.js';
 export interface ConfigRequirement {
     plugin: string;
     errors: Array<{
@@ -27,28 +28,109 @@ export interface OperationResult {
     warnings?: Array<Warning & {
         plugin?: string;
     }>;
-    /** Commands to run after this one (for example the Vite build of a new Inertia app). */
-    nextSteps?: string[];
+    /** What to do after this command: a command (or an edit) and why (D-0065). */
+    nextSteps?: NextStep[];
+    /** The version `add` picked when none was given: highest one compatible with the core. */
+    resolved?: Resolution;
     from?: string;
     to?: string;
     /** Why an upgrade to the same version was applied: the installed manifest differs (D-0037). */
     reason?: 'MANIFEST_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.
+     */
+    generatedSecrets?: GeneratedSecret[];
+}
+/** One generated secret of `add` (D-0073). */
+export interface GeneratedSecret {
+    readonly variable: string;
+    readonly file: string;
+    readonly plugin: string;
+}
+/** `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;
+    /** The plugin that hosts apps (D-0070): false skips the first `main` app (`--no-first-app`). */
+    firstApp?: boolean;
 }
+/** One follow-up of a command (init, add, app, module, recipe): a command to run and why. */
+export interface NextStep {
+    command: string;
+    why: string;
+}
+/** `dokebi init`: the created folder, plus what to do next (machine-readable). */
+export interface InitResult extends OperationResult {
+    nextSteps: NextStep[];
+}
+/**
+ * Follow-ups after init (D-0065): read the guide, pick a recipe and ask its questions, find
+ * plugins, read the core contract, and verify before saying done.
+ */
+export declare function initNextSteps(target: string): NextStep[];
+/**
+ * Entries `dokebi init` leaves in an existing folder (D-0065 §11, AI-M02: agents are often handed
+ * an empty work folder, sometimes with npm or editor files in it). Nothing here is written by init
+ * or is part of a Node project; `.npmrc` is also used for init's own npm install.
+ */
+export declare const INIT_HARMLESS: readonly string[];
+/**
+ * Whether `dokebi init` may use `target`: absent (created), or a folder that is empty or holds
+ * only INIT_HARMLESS entries (`kept`). Anything else (a file, other entries) is PROJECT_EXISTS.
+ */
+export declare function initFolder(target: string, 
+/** init's own staging folder inside `target` (checked again before the move). */
+staging?: string): Promise<{
+    exists: boolean;
+    kept: string[];
+}>;
 export declare class Project {
     #private;
     private readonly npm;
     constructor(npm?: NpmClient);
-    init(target: string, core?: string): Promise<OperationResult>;
+    init(target: string, core?: string, dryRun?: boolean): Promise<InitResult>;
     migrate(root: string, dryRun?: boolean): Promise<OperationResult>;
-    add(root: string, spec: string, dryRun?: boolean, sets?: readonly SetOption[]): 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>;
+    /**
+     * `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).
+     */
+    configSet(root: string, assignments: readonly {
+        plugin: string;
+        set: SetOption;
+    }[], dryRun?: boolean): Promise<OperationResult>;
+    /**
+     * `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.
+     */
+    devInfra(root: string, options?: {
+        dbPort?: number;
+        dryRun?: boolean;
+    }): Promise<OperationResult & {
+        service?: Record<string, unknown>;
+    }>;
+    /**
+     * `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.
+     */
+    configSecret(root: string, id: string, path: readonly string[], dryRun?: boolean): Promise<OperationResult & {
+        secret: {
+            path: string;
+            list: boolean;
+            generated: boolean;
+        };
+    }>;
     private coreVersion;
     /**
-     * `dokebi app add <name>`: copies the app skeleton of @dokebi/app to src/apps/<name>, maps the
-     * given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
+     * `dokebi app add <name>`: copies the app skeleton of the apps host (D-0070) to src/apps/<name>,
+     * maps the given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
      */
     appAdd(root: string, name: string, options?: {
         domains?: readonly string[];
@@ -78,7 +160,7 @@ export declare class Project {
         }[];
     }>;
     /**
-     * `dokebi module add <name>` (D-0032): copies the module skeleton of @dokebi/module to
+     * `dokebi module add <name>` (D-0032): copies the module skeleton of the modules host to
      * src/shared/modules/<name> and registers it in the generated code. `views: false` copies the
      * skeleton without views (routes answer JSON).
      */