@dokebi/cli 0.2.5 → 0.4.0

package/dist/check/typescript.d.ts

@@ -0,0 +1,46 @@
+/** The part of a TypeScript 7 AST node the rules read. Other fields are read with `field`. */
+export interface TsNode {
+    readonly kind: number;
+    readonly pos: number;
+    readonly end: number;
+    readonly parent?: TsNode;
+    forEachChild(visitor: (node: TsNode) => unknown): unknown;
+    getStart(): number;
+}
+export interface TsSourceFile extends TsNode {
+    readonly fileName: string;
+    readonly text: string;
+    getLineAndCharacterOfPosition(position: number): {
+        line: number;
+        character: number;
+    };
+}
+/** A child node of `node` by property name (`expression`, `block`, `name`, …). */
+export declare function field(node: TsNode, name: string): TsNode | undefined;
+/** A node list of `node` by property name (`arguments`, `statements`, `modifiers`, …). */
+export declare function nodes(node: TsNode, name: string): readonly TsNode[];
+/** A primitive property (`text` of identifiers and literals, `isExportEquals`, …). */
+export declare function property(node: TsNode, name: string): unknown;
+/** SyntaxKind names the rules use; each must exist in the loaded TypeScript. */
+declare const KIND_NAMES: readonly ['ArrowFunction', 'Block', 'CallExpression', 'CatchClause', 'Constructor', 'Decorator', 'DeclareKeyword', 'EnumDeclaration', 'ExportAssignment', 'ExportDeclaration', 'ExpressionStatement', 'ExternalModuleReference', 'FunctionExpression', 'Identifier', 'ImportDeclaration', 'ImportEqualsDeclaration', 'ImportKeyword', 'ImportType', 'InterfaceDeclaration', 'LiteralType', 'ModuleBlock', 'ModuleDeclaration', 'NewExpression', 'NoSubstitutionTemplateLiteral', 'OverrideKeyword', 'Parameter', 'ParenthesizedExpression', 'PrivateKeyword', 'PropertyAccessExpression', 'ProtectedKeyword', 'PublicKeyword', 'ReadonlyKeyword', 'StringLiteral', 'TypeAliasDeclaration', 'TypeAssertionExpression'];
+export type KindName = (typeof KIND_NAMES)[number];
+export type Kinds = Readonly<Record<KindName, number>>;
+/** An open TypeScript project: its user source files and a thenable test over the checker. */
+export interface TypeScriptProject {
+    readonly version: string;
+    readonly kinds: Kinds;
+    /** Program files under the root, outside node_modules, without declaration files. */
+    readonly files: readonly TsSourceFile[];
+    /** Milliseconds to start tsgo and load the program (the part a check cannot avoid). */
+    readonly loadMs: number;
+    /** For each expression: is its type a Promise or PromiseLike (or a union with one)? */
+    promises(expressions: readonly TsNode[]): boolean[];
+    close(): void;
+}
+/**
+ * Starts the project's TypeScript and loads the program of `<root>/tsconfig.json`. The caller
+ * closes it. Throws TYPESCRIPT_UNAVAILABLE (TypeScript missing, older than 7, or its API changed)
+ * and TSCONFIG_INVALID (the program cannot be loaded).
+ */
+export declare function openTypeScript(root: string): Promise<TypeScriptProject>;
+export {};

package/dist/check/typescript.js

@@ -0,0 +1,168 @@
+// The project's TypeScript for `dokebi check` (D-0072). TypeScript 7 (the native port that init
+// installs) exposes its parser and checker to JavaScript through `typescript/unstable/sync`: the
+// API starts the project's tsgo binary and talks to it over a pipe. The CLI does not depend on
+// TypeScript; it loads the copy the project installed, so the AST and the types are exactly what
+// `npm run typecheck` sees. The API is marked unstable, so only the few calls below are used and
+// a missing or changed API is a coded failure (TYPESCRIPT_UNAVAILABLE), never a silent pass.
+import { createRequire } from 'node:module';
+import { join, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { debug } from '../diagnostics.js';
+import { CliError } from '../errors.js';
+/** A child node of `node` by property name (`expression`, `block`, `name`, …). */
+export function field(node, name) {
+    const value = node[name];
+    return value && typeof value === 'object' && 'kind' in value ? value : undefined;
+}
+/** A node list of `node` by property name (`arguments`, `statements`, `modifiers`, …). */
+export function nodes(node, name) {
+    const value = node[name];
+    return Array.isArray(value) ? value : [];
+}
+/** A primitive property (`text` of identifiers and literals, `isExportEquals`, …). */
+export function property(node, name) {
+    return node[name];
+}
+/** SyntaxKind names the rules use; each must exist in the loaded TypeScript. */
+const KIND_NAMES = [
+    'ArrowFunction',
+    'Block',
+    'CallExpression',
+    'CatchClause',
+    'Constructor',
+    'Decorator',
+    'DeclareKeyword',
+    'EnumDeclaration',
+    'ExportAssignment',
+    'ExportDeclaration',
+    'ExpressionStatement',
+    'ExternalModuleReference',
+    'FunctionExpression',
+    'Identifier',
+    'ImportDeclaration',
+    'ImportEqualsDeclaration',
+    'ImportKeyword',
+    'ImportType',
+    'InterfaceDeclaration',
+    'LiteralType',
+    'ModuleBlock',
+    'ModuleDeclaration',
+    'NewExpression',
+    'NoSubstitutionTemplateLiteral',
+    'OverrideKeyword',
+    'Parameter',
+    'ParenthesizedExpression',
+    'PrivateKeyword',
+    'PropertyAccessExpression',
+    'ProtectedKeyword',
+    'PublicKeyword',
+    'ReadonlyKeyword',
+    'StringLiteral',
+    'TypeAliasDeclaration',
+    'TypeAssertionExpression',
+];
+function unavailable(root, message, cause) {
+    return new CliError('TYPESCRIPT_UNAVAILABLE', message, {
+        ...(cause === undefined ? {} : { cause }),
+        details: {
+            root,
+            hint: 'npm install in the project (init installs typescript 7 as a devDependency); dokebi check uses the project TypeScript API typescript/unstable/sync',
+        },
+    });
+}
+/**
+ * Starts the project's TypeScript and loads the program of `<root>/tsconfig.json`. The caller
+ * closes it. Throws TYPESCRIPT_UNAVAILABLE (TypeScript missing, older than 7, or its API changed)
+ * and TSCONFIG_INVALID (the program cannot be loaded).
+ */
+export async function openTypeScript(root) {
+    const began = performance.now();
+    const require = createRequire(join(root, 'package.json'));
+    let sync;
+    let ast;
+    let version;
+    try {
+        version = String(require('typescript/package.json').version);
+        sync = await import(pathToFileURL(require.resolve('typescript/unstable/sync')).href);
+        ast = await import(pathToFileURL(require.resolve('typescript/unstable/ast')).href);
+    }
+    catch (cause) {
+        throw unavailable(root, 'Cannot load the TypeScript 7 API of this project', cause);
+    }
+    const kinds = {};
+    for (const name of KIND_NAMES) {
+        const value = ast.SyntaxKind?.[name];
+        if (typeof value !== 'number')
+            throw unavailable(root, `TypeScript ${version} has no SyntaxKind.${name}`);
+        kinds[name] = value;
+    }
+    const anyFlags = (sync.TypeFlags?.Any ?? 0) | (sync.TypeFlags?.Unknown ?? 0);
+    if (typeof sync.API !== 'function' || !anyFlags)
+        throw unavailable(root, `TypeScript ${version} has no usable unstable/sync API`);
+    const config = join(root, 'tsconfig.json');
+    let api;
+    try {
+        api = new sync.API({ cwd: root });
+    }
+    catch (cause) {
+        throw unavailable(root, 'Cannot start the TypeScript API (tsgo)', cause);
+    }
+    let project;
+    try {
+        project = api.updateSnapshot({ openProject: config }).getProject(config);
+    }
+    catch (cause) {
+        api.close();
+        throw new CliError('TSCONFIG_INVALID', `TypeScript cannot load ${config}`, {
+            cause,
+            details: { tsconfig: config },
+        });
+    }
+    if (!project) {
+        api.close();
+        throw new CliError('TSCONFIG_INVALID', `TypeScript has no project for ${config}`, {
+            details: { tsconfig: config },
+        });
+    }
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    const modules = `${prefix}node_modules${sep}`;
+    const files = [];
+    for (const name of project.program.getSourceFileNames()) {
+        const native = name.split('/').join(sep);
+        if (!native.startsWith(prefix) || native.startsWith(modules))
+            continue;
+        if (!/\.(c|m)?tsx?$/.test(native) || /\.d\.(c|m)?ts$/.test(native))
+            continue;
+        const file = project.program.getSourceFile(name);
+        if (file)
+            files.push(file);
+    }
+    // The program loads lazily on the first file request, so the load ends here.
+    const loadMs = Math.round(performance.now() - began);
+    debug('check: TypeScript program loaded', { version, files: files.length, loadMs });
+    const checker = project.checker;
+    // A Promise (or PromiseLike) — not any object with a `then`: Fastify's reply and query
+    // builders are thenables whose methods return themselves, and leaving those alone is fine.
+    const promiseType = (type, depth) => {
+        if (!type || depth > 4 || type.flags & anyFlags)
+            return false;
+        if (type.isUnionType())
+            return (type.getTypes?.() ?? []).some((member) => promiseType(member, depth + 1));
+        const name = type.getSymbol?.()?.name;
+        return name === 'Promise' || name === 'PromiseLike';
+    };
+    return {
+        version,
+        kinds,
+        files,
+        loadMs,
+        promises(expressions) {
+            if (!expressions.length)
+                return [];
+            return checker.getTypeAtLocation(expressions).map((type) => promiseType(type, 0));
+        },
+        close() {
+            api.close();
+        },
+    };
+}

package/dist/commands.d.ts

@@ -0,0 +1,18 @@
+/** One command of `dokebi --help`: its usage lines (format kept stable) and what it does. */
+export interface CommandHelp {
+    readonly name: string;
+    readonly usage: string;
+    readonly summary: string;
+}
+/**
+ * Every command with its usage line. scripts/catalog/check.ts reads this list (from dist) to
+ * prove that an absent entry's `no-flag:<command> <flag>` still holds (D-0065).
+ */
+export declare const COMMANDS: readonly CommandHelp[];
+/** True when the usage line of `dokebi <command>` names `flag` (absent `no-flag:` rules). */
+export declare function commandHasFlag(command: string, flag: string): boolean;
+/** `dokebi <command> --help`: what each flag does, and one example (D-0065, AI-M01). */
+export declare const COMMAND_DETAILS: Readonly<Record<string, {
+    readonly flags: readonly (readonly [string, string])[];
+    readonly example: string;
+}>>;

package/dist/commands.js

@@ -0,0 +1,372 @@
+/**
+ * Every command with its usage line. scripts/catalog/check.ts reads this list (from dist) to
+ * prove that an absent entry's `no-flag:<command> <flag>` still holds (D-0065).
+ */
+export const COMMANDS = [
+    {
+        name: 'guide',
+        usage: 'dokebi guide [--json]',
+        summary: 'AI first page: how to turn a one-line request into an app (ask, install, verify) — read this first',
+    },
+    {
+        name: 'init',
+        usage: 'dokebi init <directory> [--core <package|local.tgz>] [--dry-run] [--json]',
+        summary: 'Create a project (new folder, or an empty one such as .) with core, config, this CLI (@dokebi/cli) and TypeScript; prints next steps',
+    },
+    {
+        name: 'recipe list',
+        usage: 'dokebi recipe list [--json]',
+        summary: 'List recipes (blog, api, …): what each builds and which questions it asks',
+    },
+    {
+        name: 'recipe',
+        usage: 'dokebi recipe <name> [--dir <directory>] [--view <v>] [--db <d>] [--dev-infra <i>] [--admin <a>] [--port <n>] [--db-port <n>] [--answers-from <user|defaults>] [--defaults] [--dry-run] [--json]',
+        summary: "Without every answer: the questions to ask the user, then end your turn (installs nothing); with the user's answers: plan, then apply with --answers-from user",
+    },
+    {
+        name: 'plugins list',
+        usage: 'dokebi plugins list [--compatible] [--online] [--json]',
+        summary: 'Every Dokebi package with summary, capabilities and install state',
+    },
+    {
+        name: 'plugins search',
+        usage: 'dokebi plugins search <words|capability>... [--json]',
+        summary: 'Find packages by words or capability; nothing found returns what Dokebi does not have',
+    },
+    {
+        name: 'plugins info',
+        usage: 'dokebi plugins info <id|package> [--json]',
+        summary: 'One package: capabilities, variants, what it does not do, requirements, options',
+    },
+    {
+        name: 'plugins doc',
+        usage: 'dokebi plugins doc <id|package> [--json]',
+        summary: 'Path and content of the installed version AI.md (read it before writing code)',
+    },
+    {
+        name: 'add',
+        usage: 'dokebi add <package|local.tgz> [--set <path>=<value>]... [--adapter <pg|mysql2|mariadb|mongodb>] [--no-first-app] [--dry-run] [--json]',
+        summary: 'Install and register a plugin (and the plugins it requires); no version picks the newest one for this core',
+    },
+    {
+        name: 'upgrade',
+        usage: 'dokebi upgrade <plugin-id> [--to <version|package|local.tgz>] [--dry-run] [--json]',
+        summary: 'Change the version of an installed plugin',
+    },
+    {
+        name: 'remove',
+        usage: 'dokebi remove <plugin-id> [--dry-run] [--json]',
+        summary: 'Unregister and uninstall a plugin; user options are kept and marked',
+    },
+    {
+        name: 'config set',
+        usage: 'dokebi config set <plugin-id>.<path>=<value>... [--dry-run] [--json]',
+        summary: 'Set non-secret options in dokebi.yaml (checked against the plugin schema)',
+    },
+    {
+        name: 'config secret',
+        usage: 'dokebi config secret <plugin-id>.<path> [--dry-run] [--json]',
+        summary: 'Write a generated secret (never shown) into dokebi.yaml, e.g. dokebi-session.secrets',
+    },
+    {
+        name: 'dev-infra',
+        usage: 'dokebi dev-infra [--db-port <n>] [--dry-run] [--json]',
+        summary: 'Write compose.yaml, .env (generated password) and the dokebi.yaml address of the development database',
+    },
+    {
+        name: 'migrate',
+        usage: 'dokebi migrate [--dry-run] [--json]',
+        summary: 'Move a 0.1.x JSON-configured project to dokebi.yaml',
+    },
+    {
+        name: 'inspect',
+        usage: 'dokebi inspect [--verbose] [--json]',
+        summary: 'Show plugins, versions, documentation and optionsSchema paths, diagnostics',
+    },
+    {
+        name: 'doctor',
+        usage: 'dokebi doctor [--verbose] [--json]',
+        summary: 'Run all checks; exit 1 on an error diagnostic (repairs nothing)',
+    },
+    {
+        name: 'check',
+        usage: 'dokebi check [--json]',
+        summary: 'User-code conventions: empty catch, floating promises, syntax Node cannot strip, private or missing @dokebi imports, edited generated files, committable secrets',
+    },
+    {
+        name: 'verify',
+        usage: 'dokebi verify [--wait-ms <ms>] [--json]',
+        summary: 'doctor, check, typecheck, build, start, HTTP checks and stop; ok only when all pass (say done only then)',
+    },
+    {
+        name: 'app add',
+        usage: 'dokebi app add <name> [--domain <host>]... [--template <name>] [--inertia [--ssr]] [--dry-run] [--json]',
+        summary: 'Create the app src/apps/<name> (EJS, or Vue with --inertia) and map its domains',
+    },
+    {
+        name: 'app remove',
+        usage: 'dokebi app remove <name> [--dry-run] [--json]',
+        summary: 'Unregister an app (unlink its domains first); its folder is kept',
+    },
+    {
+        name: 'app link',
+        usage: 'dokebi app link <name> <domain> [--template <name>] [--dry-run] [--json]',
+        summary: 'Serve an app on one more domain, optionally with another template',
+    },
+    {
+        name: 'app unlink',
+        usage: 'dokebi app unlink <domain> [--dry-run] [--json]',
+        summary: 'Remove a domain from its app',
+    },
+    { name: 'app list', usage: 'dokebi app list [--json]', summary: 'List apps and their domains' },
+    {
+        name: 'module add',
+        usage: 'dokebi module add <name> [--no-views] [--dry-run] [--json]',
+        summary: 'Create the feature module src/shared/modules/<name>',
+    },
+    {
+        name: 'module remove',
+        usage: 'dokebi module remove <name> [--dry-run] [--json]',
+        summary: 'Unregister a feature module; its folder is kept',
+    },
+    { name: 'module list', usage: 'dokebi module list [--json]', summary: 'List feature modules' },
+    {
+        name: 'dev',
+        usage: 'dokebi dev',
+        summary: 'Run the app in the foreground and restart it when src or dokebi.yaml change',
+    },
+    {
+        name: 'start',
+        usage: 'dokebi start [--foreground] [--wait-ms <ms>] [--log-max-mb <MB>] [--log-files <n>] [--json]',
+        summary: 'Start the app in the background with rotated logs in .dokebi/run',
+    },
+    {
+        name: 'stop',
+        usage: 'dokebi stop [--timeout-ms <ms>] [--force] [--json]',
+        summary: 'Stop the background app (SIGTERM drain; SIGKILL with --force after the timeout)',
+    },
+    {
+        name: 'status',
+        usage: 'dokebi status [--json]',
+        summary: 'Show whether the background app runs (exit 3 when stopped)',
+    },
+    {
+        name: 'logs',
+        usage: 'dokebi logs [-n <lines>] [-f]',
+        summary: 'Print the last log lines of the background app; -f follows',
+    },
+];
+/** True when the usage line of `dokebi <command>` names `flag` (absent `no-flag:` rules). */
+export function commandHasFlag(command, flag) {
+    const usage = COMMANDS.find((item) => item.name === command)?.usage;
+    if (usage === undefined)
+        return false;
+    return new RegExp(`(^|[\\s\\[|])${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[\\s\\]|]|$)`).test(usage);
+}
+/** `dokebi <command> --help`: what each flag does, and one example (D-0065, AI-M01). */
+export const COMMAND_DETAILS = {
+    guide: {
+        flags: [['--json', 'the guide as data: steps, rules, recipes, absent, commands']],
+        example: 'npx dokebi guide --json',
+    },
+    init: {
+        flags: [
+            ['--core <package|local.tgz>', 'core to install (default: @dokebi/core in this CLI range)'],
+            [
+                '<directory>',
+                'a new folder, or an existing one that is empty or holds only .git, .npmrc, .npm, .npm-cache, .DS_Store, Thumbs.db, .idea, .vscode (init . works there); anything else is PROJECT_EXISTS',
+            ],
+            ['--dry-run', 'check the folder and print the next steps; nothing is installed or written'],
+        ],
+        example: 'npx -y @dokebi/cli init my-blog && cd my-blog && npx dokebi guide --json\nnpx -y @dokebi/cli init . --json   # in an empty work folder',
+    },
+    'recipe list': { flags: [], example: 'npx dokebi recipe list --json' },
+    recipe: {
+        flags: [
+            [
+                '--dir <directory>',
+                'project folder; a new folder is created with init first (default: current project)',
+            ],
+            ['--view <v>', 'blog: ejs | inertia-vue | inertia-vue-ssr (inertia-react is absent)'],
+            ['--db <d>', 'postgres | mysql | mariadb | mongodb | none (sqlite is absent)'],
+            [
+                '--dev-infra <i>',
+                'docker (compose.yaml, generated password) | url (you write the URL); only with a database',
+            ],
+            ['--admin <a>', 'blog: none | app-code (no auth plugin: the app writes the login)'],
+            ['--port <n>', 'web port (default 3000)'],
+            [
+                '--db-port <n>',
+                'host port of the docker database (default: the database default, e.g. 5432)',
+            ],
+            [
+                '--answers-from <user|defaults>',
+                'where the answers came from; applying needs it. user: the user answered these questions (ask, end your turn, wait). defaults: the user said to decide (same as --defaults). Recorded in `answersFrom` and `report`',
+            ],
+            [
+                '--defaults',
+                'fill unanswered questions with defaults: only when the user left the choice to you; tell the user `report`',
+            ],
+            ['--dry-run', 'plan and preflight only; nothing is written'],
+        ],
+        example: 'npx dokebi recipe blog --json   # the questions (exit 2, nothing installed): ask them and end your turn\nnpx dokebi recipe blog --view ejs --db postgres --dev-infra docker --admin none --answers-from user --dry-run --json',
+    },
+    'plugins list': {
+        flags: [
+            ['--compatible', 'only packages whose core range accepts this project core'],
+            [
+                '--online',
+                'ask the registry for the latest and compatible versions (CATALOG_OFFLINE when it cannot)',
+            ],
+        ],
+        example: 'npx dokebi plugins list --compatible --json',
+    },
+    'plugins search': {
+        flags: [],
+        example: 'npx dokebi plugins search login --json   # status: absent (auth)',
+    },
+    'plugins info': { flags: [], example: 'npx dokebi plugins info db --json' },
+    'plugins doc': { flags: [], example: 'npx dokebi plugins doc dokebi-db --json' },
+    add: {
+        flags: [
+            [
+                '<package>',
+                'registry name (no version: newest for this core, see `resolved`) or a local .tgz',
+            ],
+            [
+                '--set <path>=<value>',
+                'non-secret option of the added plugin (repeatable); secrets go in dokebi.yaml',
+            ],
+            [
+                '--adapter <id>',
+                '@dokebi/db: pg | mysql2 | mariadb | mongodb (adapter file, connection main, driver, @types/pg)',
+            ],
+            [
+                '--no-first-app',
+                '@dokebi/app: do not create the EJS app main (add the first app with app add)',
+            ],
+            ['--dry-run', 'plan only; packages may be downloaded into a temporary folder'],
+        ],
+        example: 'npx dokebi add @dokebi/db --adapter pg --dry-run --json',
+    },
+    upgrade: {
+        flags: [
+            ['--to <version|package|local.tgz>', 'target (default: latest)'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi upgrade dokebi-web --to 0.4.0 --dry-run --json',
+    },
+    remove: {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi remove dokebi-health --dry-run --json',
+    },
+    'config set': {
+        flags: [
+            ['<id>.<path>=<value>', 'JSON when it parses, else text; checked against the plugin schema'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi config set dokebi-web.port=3000 --json',
+    },
+    'config secret': {
+        flags: [
+            [
+                '<id>.<path>',
+                'writes a random secret there (a list when the schema wants one); never printed',
+            ],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi config secret dokebi-session.secrets --json',
+    },
+    'dev-infra': {
+        flags: [
+            ['--db-port <n>', 'host port of the database container (PORT_IN_USE names a free one)'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi dev-infra --db-port 5433 --json && docker compose up -d --wait',
+    },
+    migrate: { flags: [['--dry-run', 'plan only']], example: 'npx dokebi migrate --dry-run --json' },
+    inspect: {
+        flags: [['--verbose', 'the whole inspection (default: a summary; --json is always complete)']],
+        example: 'npx dokebi inspect --json',
+    },
+    doctor: {
+        flags: [['--verbose', 'the whole inspection (default: a summary; --json is always complete)']],
+        example: 'npx dokebi doctor',
+    },
+    check: {
+        flags: [
+            [
+                '--json',
+                '{ ok, problems[{rule, file, line, message, fix}], files, ms }; exit 1 on a problem',
+            ],
+        ],
+        example: 'npx dokebi check --json\n# a justified empty catch or background promise: // dokebi-check: allow empty-catch <reason>',
+    },
+    verify: {
+        flags: [['--wait-ms <ms>', 'how long start waits for the started line (default 30000)']],
+        example: 'npx dokebi verify --json',
+    },
+    'app add': {
+        flags: [
+            ['--domain <host>', 'host name served by the app (repeatable, no port)'],
+            ['--template <name>', 'views folder for those domains (default: default)'],
+            ['--inertia', 'Vue pages with Vite (adds vite.config.ts, the build script, vite and vue)'],
+            ['--ssr', 'with --inertia: server-rendered first HTML'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi app add admin --domain admin.localhost --inertia --json',
+    },
+    'app remove': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi app remove admin --json',
+    },
+    'app link': {
+        flags: [
+            ['--template <name>', 'views folder for this domain'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi app link shop sale.localhost --template sale --json',
+    },
+    'app unlink': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi app unlink sale.localhost --json',
+    },
+    'app list': { flags: [], example: 'npx dokebi app list --json' },
+    'module add': {
+        flags: [
+            ['--no-views', 'routes answer JSON (no views folder)'],
+            ['--dry-run', 'plan only'],
+        ],
+        example: 'npx dokebi module add posts --json',
+    },
+    'module remove': {
+        flags: [['--dry-run', 'plan only']],
+        example: 'npx dokebi module remove posts --json',
+    },
+    'module list': { flags: [], example: 'npx dokebi module list --json' },
+    dev: { flags: [], example: 'npx dokebi dev' },
+    start: {
+        flags: [
+            ['--foreground', 'run in this terminal (systemd, Docker); no --json'],
+            ['--wait-ms <ms>', 'wait for the started line (default 10000)'],
+            ['--log-max-mb <MB>', 'rotate app.log at this size (default 50)'],
+            ['--log-files <n>', 'rotated files kept (default 5)'],
+        ],
+        example: 'npx dokebi start --json',
+    },
+    stop: {
+        flags: [
+            ['--timeout-ms <ms>', 'drain time before STOP_TIMEOUT (default 30000)'],
+            ['--force', 'SIGKILL after the timeout'],
+        ],
+        example: 'npx dokebi stop --json',
+    },
+    status: { flags: [], example: 'npx dokebi status --json' },
+    logs: {
+        flags: [
+            ['-n <lines>', 'last lines (default 100)'],
+            ['-f', 'follow until Ctrl+C'],
+        ],
+        example: 'npx dokebi logs -n 50',
+    },
+};

package/dist/config-edit.d.ts

@@ -13,11 +13,12 @@ export declare function setWarnings(sets: readonly SetOption[]): Warning[];
 export declare function applySetOptions(source: string, id: string, sets: readonly SetOption[]): string;
 export declare function applyConfigChanges(source: string, id: string, changes: readonly ConfigChange[]): string;
 /**
- * Removes `options.dokebi-app.apps.<app>` (D-0061 per-app settings) and the `apps` map when it is
- * left empty; a source without that entry is returned unchanged. dokebi-app refuses to start with
- * an entry for an app that is not defined (UNKNOWN_APP), so `dokebi app remove` calls this.
+ * Removes `options.<host>.apps.<app>` (D-0061 per-app settings of the apps host, D-0070) and the
+ * `apps` map when it is left empty; a source without that entry is returned unchanged. The host
+ * refuses to start with an entry for an app that is not defined (UNKNOWN_APP), so
+ * `dokebi app remove` calls this.
  */
-export declare function removeAppSettings(source: string, app: string): string;
+export declare function removeAppSettings(source: string, host: string, app: string): string;
 /** Keeps a removed plugin's section and marks it for a later reinstall or manual cleanup. */
 export declare function markRemoved(source: string, id: string): {
     source: string;

package/dist/config-edit.js

@@ -110,19 +110,20 @@ export function applyConfigChanges(source, id, changes) {
     });
 }
 /**
- * Removes `options.dokebi-app.apps.<app>` (D-0061 per-app settings) and the `apps` map when it is
- * left empty; a source without that entry is returned unchanged. dokebi-app refuses to start with
- * an entry for an app that is not defined (UNKNOWN_APP), so `dokebi app remove` calls this.
+ * Removes `options.<host>.apps.<app>` (D-0061 per-app settings of the apps host, D-0070) and the
+ * `apps` map when it is left empty; a source without that entry is returned unchanged. The host
+ * refuses to start with an entry for an app that is not defined (UNKNOWN_APP), so
+ * `dokebi app remove` calls this.
  */
-export function removeAppSettings(source, app) {
-    const path = ['options', 'dokebi-app', 'apps', app];
+export function removeAppSettings(source, host, app) {
+    const path = ['options', host, 'apps', app];
     if (!parseDocument(source, { version: '1.2' }).hasIn(path))
         return source;
-    return edit(source, 'dokebi-app', (document) => {
+    return edit(source, host, (document) => {
         document.deleteIn(path);
-        const apps = document.getIn(['options', 'dokebi-app', 'apps'], true);
+        const apps = document.getIn(['options', host, 'apps'], true);
         if (isMap(apps) && apps.items.length === 0)
-            document.deleteIn(['options', 'dokebi-app', 'apps']);
+            document.deleteIn(['options', host, 'apps']);
     });
 }
 /** Keeps a removed plugin's section and marks it for a later reinstall or manual cleanup. */

package/dist/configuration.d.ts

@@ -12,6 +12,7 @@ export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committ
  * file started from `options: {}`. Values are unchanged; only the layout is normalized.
  */
 export declare function renderConfig(document: Document): string;
+/** Never committed: real settings, the legacy backup and the generated secrets in .env (D-0073). */
 export declare const CONFIG_IGNORES: string[];
 export declare function parseProjectConfig(source: string): ProjectConfig;
 export declare function addConfigSection(source: string, id: string): string;