@dokebi/cli 0.4.2 → 0.4.27

package/dist/deployment.js

@@ -0,0 +1,111 @@
+/** Optional, editable deployment files written atomically with a new project. */
+export const DEPLOYMENT_FILES = {
+    Dockerfile: `# syntax=docker/dockerfile:1
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+# Optional private registry credentials: docker build --secret id=npmrc,src=/path/to/.npmrc .
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
+COPY . .
+RUN npm run build --if-present && npm prune --omit=dev
+
+FROM node:24-bookworm-slim AS runtime
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build --chown=node:node /app /app
+USER node
+STOPSIGNAL SIGTERM
+CMD ["node", "src/main.ts"]
+`,
+    '.dockerignore': `# Explicit build inputs. Add other non-secret assets when the application needs them.
+**
+!package.json
+!package-lock.json
+!src/
+!src/**
+!public/
+!public/**
+!tsconfig*.json
+!vite*.config.*
+# Keep credentials and local artifacts out even under an allowed directory.
+**/node_modules
+**/.git
+**/.env
+**/.env.*
+**/.npmrc
+**/dokebi.yaml
+**/*.backup
+**/*.test.*
+**/.DS_Store
+`,
+    'compose.deploy.yaml': `# Separate from local database/mail Compose files. Configure the app before starting.
+# The container reads deploy/dokebi.yaml, never the project's dokebi.yaml, which npx dokebi
+# start, dev and verify read on this machine (DEPLOY.md, step 3).
+services:
+  app:
+    build:
+      context: .
+    init: true
+    user: "\${DOKEBI_UID:-1000}:\${DOKEBI_GID:-1000}"
+    environment:
+      NODE_ENV: production
+    ports:
+      - "127.0.0.1:\${DOKEBI_HTTP_PORT:-3000}:3000"
+    volumes:
+      - type: bind
+        source: ./deploy/dokebi.yaml
+        target: /app/dokebi.yaml
+        read_only: true
+        bind:
+          create_host_path: false
+    stop_grace_period: 60s
+    restart: unless-stopped
+`,
+    'DEPLOY.md': `# Deployment
+
+These editable files are an application container skeleton. They do not provision a server,
+TLS, databases, queues or backups. Finish your app or recipe and verify it before deploying.
+A new core-only project has no long-running server and exits normally.
+
+1. Commit source and package-lock.json. Keep real dokebi.yaml, .env and credentials out of Git.
+2. Build with \`docker compose -f compose.deploy.yaml build\`. The build runs npm ci,
+   the optional build script (including Inertia assets/SSR), then removes devDependencies.
+   Put every package imported by the running app or SSR bundle in dependencies.
+3. Create deploy/dokebi.yaml, the container's settings, from dokebi.example.yaml. It is not
+   the project's dokebi.yaml: npx dokebi start, dev and verify read that one on the machine,
+   so container values (host 0.0.0.0, host.docker.internal, a database host of the container
+   network, paths inside the image) never go into it, and no release script writes it.
+   Both files stay out of Git and out of the image (.gitignore, .dockerignore). For a web app, set options.dokebi-web.host to 0.0.0.0 and port to 3000; configure
+   options.dokebi-app.domains for your public domain. Use production database/queue endpoints:
+   localhost inside a container is that container. Provision queues and run migrations as a
+   separate deployment step before starting traffic; never seed or migrate on every boot.
+4. Keep deploy/dokebi.yaml mode 0600 and owned by the container user (default UID/GID 1000:1000 on Linux).
+   To use another non-root UID/GID set DOKEBI_UID and DOKEBI_GID in the deployment environment.
+   The mount is read-only and refuses a missing file. Do not make credentials world-readable.
+5. Start with \`docker compose -f compose.deploy.yaml up -d\`. The host port defaults to
+   127.0.0.1:3000 (DOKEBI_HTTP_PORT changes it). Terminate HTTPS in your reverse proxy and
+   configure only its trusted addresses in dokebi-web.trustProxy. For mail set siteUrl to
+   the public HTTPS origin. A worker-only app can remove the ports mapping.
+6. Inspect \`docker compose -f compose.deploy.yaml logs app\`; stop using
+   \`docker compose -f compose.deploy.yaml stop\`. Node runs in the foreground, receives
+   SIGTERM and drains. Set stop_grace_period above your configured total drain/cleanup budget.
+
+The Docker build accepts only the inputs listed in .dockerignore. Add custom asset directories
+there when needed, keeping credential exclusions last. The YAML is mounted at runtime and is
+never an image layer. An authenticated npm registry can use BuildKit's secret mount:
+\`docker build --secret id=npmrc,src=/private/path/.npmrc -t my-app .\`.
+Do not COPY .npmrc or pass tokens as build arguments. Use registry-resolvable dependencies;
+local tarball paths and workspace links need a separately prepared build context. npm lifecycle
+and build scripts run without production credentials: they must not require dokebi.yaml.
+
+Add readiness checks for the services you actually install and configure persistent storage for
+uploads or other app-owned files. The skeleton does not invent an HTTP health endpoint or
+silently install a web/health plugin. Pin the Node image digest in your deployment process.
+
+An Inertia app run as several containers that are replaced one by one (a rolling update behind
+a load balancer) serves two builds side by side, and each image holds only the chunks of its own
+build: a page of the old build then misses its chunks on a new container. Carry the previous
+build's dist/assets into the new image, or serve dist/assets from storage every container
+shares (node_modules/@dokebi/template-inertia/AI.md, "Rolling deploys").
+`,
+};

package/dist/describe-db.d.ts

@@ -0,0 +1,22 @@
+/** Why `db` has no tables without --with-db. */
+export declare const DB_NOT_READ = "not read: dokebi describe --with-db reads the tables (it connects to each database)";
+export interface DbConnection {
+    readonly name: string;
+    readonly adapter: string;
+    /** D-0127: `optional` when dokebi.yaml says so (the default `required` is left out). */
+    readonly startup?: string;
+    readonly dialect?: string;
+    readonly schemas?: readonly string[];
+    readonly tables?: readonly unknown[];
+    readonly collections?: readonly unknown[];
+    readonly unavailable?: string;
+}
+/**
+ * The `db.connections` of `describe --with-db`: every dokebi-db connection with its dialect and
+ * tables (collections), or `unavailable` and why. The reads run side by side.
+ */
+export declare function describeDatabases(root: string, connections: readonly {
+    name: string;
+    adapter: string;
+    startup?: string;
+}[], timeoutMs: number): Promise<DbConnection[]>;

package/dist/describe-db.js

@@ -0,0 +1,176 @@
+// `dokebi describe --with-db` (D-0077 F): the tables of each dokebi-db connection. Describe mode
+// itself never connects (D-0077 B), so this is a separate step that does: for each connection it
+// runs the project's own `dokebi-migrate schema --connection <name> --json` (the bin of the
+// installed @dokebi/migrate, in the project folder, with the project's .env like describe). A
+// connection that cannot be read gets `unavailable` with the reason; describe itself goes on.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { redaction } from '@dokebi/core/libraries';
+import { debug, describeError } from './diagnostics.js';
+import { appEnvironment } from './env-file.js';
+/** Why `db` has no tables without --with-db. */
+export const DB_NOT_READ = 'not read: dokebi describe --with-db reads the tables (it connects to each database)';
+/** @dokebi/migrate 0.4.2 has the schema command. */
+const MIGRATE_SCHEMA_VERSION = [0, 4, 2];
+/** The largest answer read from one connection (a very large schema is cut, not buffered). */
+const MAX_OUTPUT = 32 * 1024 * 1024;
+/** One line, URL credentials removed, at most 500 characters. */
+function reason(text) {
+    return (redaction
+        .maskCredentials(text.split('\n', 1)[0] ?? '')
+        .trim()
+        .slice(0, 500) || 'Unknown error');
+}
+/** The installed @dokebi/migrate (walking up like Node's resolution): its bin and version. */
+function migratePackage(root) {
+    for (let directory = root;; directory = dirname(directory)) {
+        const folder = join(directory, 'node_modules', '@dokebi', 'migrate');
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(join(folder, 'package.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                debug('Unable to read the installed @dokebi/migrate package.json', {
+                    error: describeError(error),
+                });
+        }
+        if (manifest) {
+            const bin = typeof manifest.bin === 'string'
+                ? manifest.bin
+                : manifest.bin?.['dokebi-migrate'];
+            if (typeof bin !== 'string')
+                return undefined;
+            const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(String(manifest.version));
+            return {
+                bin: join(folder, bin),
+                version: parts ? [Number(parts[1]), Number(parts[2]), Number(parts[3])] : undefined,
+            };
+        }
+        if (dirname(directory) === directory)
+            return undefined;
+    }
+}
+const older = (a, b) => {
+    for (let index = 0; index < 3; index++)
+        if ((a[index] ?? 0) !== (b[index] ?? 0))
+            return (a[index] ?? 0) < (b[index] ?? 0);
+    return false;
+};
+/** Runs `dokebi-migrate schema` for one connection; resolves with the shape or a reason. */
+function readOne(root, bin, name, timeoutMs) {
+    const started = Date.now();
+    const child = spawn(process.execPath, [bin, 'schema', '--connection', name, '--json'], {
+        cwd: root,
+        // The project's .env under the CLI's environment, like describe and dokebi start (D-0073).
+        env: appEnvironment(root, 'production'),
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let cut = false;
+    // Its log lines (stderr) are kept only for the reason of a failure; never printed.
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+        if (stdout.length + chunk.length > MAX_OUTPUT)
+            cut = true;
+        else
+            stdout += chunk.toString('utf8');
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr = (stderr + chunk.toString('utf8')).slice(-16_384);
+    });
+    let timedOut = false;
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            timedOut = true;
+            debug('Database schema read timed out', { connection: name, timeoutMs });
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            debug('Database schema read', {
+                connection: name,
+                ok: 'shape' in value,
+                ms: Date.now() - started,
+            });
+            resolve(value);
+        };
+        child.once('error', (error) => {
+            debug('Unable to run dokebi-migrate schema', {
+                connection: name,
+                error: describeError(error),
+            });
+            finish({ unavailable: `dokebi-migrate could not run: ${reason(error.message)}` });
+        });
+        child.once('close', (code, signal) => {
+            if (timedOut) {
+                finish({ unavailable: `DESCRIBE_TIMEOUT: no answer within ${timeoutMs} ms` });
+                return;
+            }
+            if (cut) {
+                finish({ unavailable: `SCHEMA_TOO_LARGE: more than ${MAX_OUTPUT} bytes` });
+                return;
+            }
+            let answer;
+            try {
+                answer = JSON.parse(stdout);
+            }
+            catch (error) {
+                debug('dokebi-migrate schema did not answer JSON', {
+                    connection: name,
+                    exit: code ?? signal,
+                    error: describeError(error),
+                    output: reason(stderr.split('\n').filter(Boolean).at(-1) ?? ''),
+                });
+                finish({
+                    unavailable: `dokebi-migrate schema exited (${code ?? signal}) without a result`,
+                });
+                return;
+            }
+            const shape = answer.results?.[name];
+            if (answer.ok === true && shape !== null && typeof shape === 'object') {
+                finish({ shape: shape });
+                return;
+            }
+            const failure = answer.error ?? {};
+            finish({
+                unavailable: reason(`${typeof failure.code === 'string' ? failure.code : 'SCHEMA_FAILED'}: ${String(failure.message ?? 'no message')}`),
+            });
+        });
+    });
+}
+/**
+ * The `db.connections` of `describe --with-db`: every dokebi-db connection with its dialect and
+ * tables (collections), or `unavailable` and why. The reads run side by side.
+ */
+export async function describeDatabases(root, connections, timeoutMs) {
+    if (!connections.length)
+        return [];
+    const installed = migratePackage(root);
+    const missing = !installed
+        ? '@dokebi/migrate is not installed: npx dokebi add @dokebi/migrate, then list the connection in options.dokebi-migrate.connections'
+        : installed.version && older(installed.version, MIGRATE_SCHEMA_VERSION)
+            ? `@dokebi/migrate ${installed.version.join('.')} has no schema command (0.4.2 or later)`
+            : undefined;
+    debug('Reading the database schemas', {
+        connections: connections.length,
+        migrate: installed?.version?.join('.') ?? null,
+    });
+    return Promise.all(connections.map(async ({ name, adapter, startup }) => {
+        // D-0127: the policy stays next to the name; `dokebi-migrate schema` opens every
+        // connection as required, so an optional one that is down is `unavailable` with why.
+        const base = { name, adapter, ...(startup === undefined ? {} : { startup }) };
+        if (missing || !installed)
+            return { ...base, unavailable: missing ?? 'unknown' };
+        const read = await readOne(root, installed.bin, name, timeoutMs);
+        if ('unavailable' in read)
+            return { ...base, unavailable: read.unavailable };
+        const { schemaVersion: _version, connection: _connection, ...shape } = read.shape;
+        return { ...base, ...shape };
+    }));
+}

package/dist/describe.d.ts

@@ -0,0 +1,92 @@
+/** The JSON Schema of `result` (shipped next to dist/: packages/cli/describe.schema.json). */
+export declare const DESCRIBE_SCHEMA_FILE = "describe.schema.json";
+export declare const DESCRIBE_SCHEMA_VERSION = 1;
+/** Default limit for loading and describing the app. */
+export declare const DESCRIBE_TIMEOUT_MS = 30000;
+/**
+ * Runs in the project's folder (`node --input-type=module --eval`): bare specifiers resolve from
+ * the project's node_modules and relative ones from its root, like src/main.ts.
+ */
+export declare const DESCRIBE_RUNNER = "import { existsSync } from 'node:fs';\nimport { pathToFileURL } from 'node:url';\nconst base = pathToFileURL(process.cwd() + '/');\nconst reason = (error) => {\n  let text;\n  try { text = error instanceof Error ? error.message : String(error); } catch { text = typeof error; }\n  return (String(text).split('\\n', 1)[0] || 'Unknown error').replace(/\\/\\/[^\\s/]*@/g, '//***@').slice(0, 500);\n};\nconst answer = (message) =>\n  new Promise((resolve) => process.send(message, () => resolve(undefined)));\ntry {\n  const { Application, loadConfig, definePoint } = await import('@dokebi/core');\n  if (typeof Application.prototype.describe !== 'function') {\n    await answer({ type: 'failure', code: 'DESCRIBE_UNSUPPORTED', message: 'The installed @dokebi/core cannot describe an app' });\n  } else {\n    // M50: the settings file the app reads, resolved by the CLI (DOKEBI_CONFIG, else dokebi.yaml).\n    const settings = process.env.DOKEBI_CLI_SETTINGS_FILE;\n    const document = await loadConfig(settings ? settings : new URL('dokebi.yaml', base));\n    const app = new Application({ config: document.options, runtime: { describing: true } });\n    const { registerPlugins } = await import(new URL('src/dokebi.generated.ts', base).href);\n    await registerPlugins(app);\n    const previewInput = process.env.DOKEBI_CLI_MAIL_PREVIEW;\n    if (previewInput) {\n      const input = JSON.parse(previewInput);\n      const { dependency } = await import('@dokebi/mail');\n      const point = definePoint('core:describe');\n      app.register({\n        metadata: { name: 'cli-mail-preview', version: '1.0.0', core: '*', dependencies: [dependency], contributes: ['core:describe'] },\n        setup(context) {\n          const mail = context.getDependency(dependency);\n          context.logger.log('debug', 'Preparing mail template preview', { template: input.name });\n          context.contribute(point, { section: 'mail-preview', describe: async () => {\n            if (typeof mail.preview !== 'function') throw Object.assign(new Error('Upgrade @dokebi/mail for template preview'), { code: 'MAIL_PREVIEW_UNSUPPORTED' });\n            const result = await mail.preview(input.name, input.locale);\n            if (!result) throw Object.assign(new Error('Mail template does not exist'), { code: 'MAIL_TEMPLATE_NOT_FOUND' });\n            return result;\n          } });\n        },\n      });\n    }\n    const description = await app.describe();\n    let errors = { file: false };\n    const file = new URL('src/shared/errors.ts', base);\n    if (existsSync(file)) {\n      try {\n        const module = await import(file.href);\n        // errorCatalog of @dokebi/web 0.4.3 (D-0077 D) joins every defineErrors result exported.\n        const web = await import('@dokebi/web');\n        if (typeof web.errorCatalog !== 'function') throw Object.assign(new Error('The installed @dokebi/web has no errorCatalog (0.4.3 or later)'), { code: 'ERRORS_UNREADABLE' });\n        const definitions = (web.errorCatalog(module) ?? []).map((item) => ({\n          code: item.code,\n          status: item.status,\n          message: item.message,\n          ...(typeof item.hint === 'string' ? { hint: item.hint } : {}),\n        }));\n        errors = { file: true, definitions };\n      } catch (error) {\n        errors = { file: true, failure: { code: typeof error?.code === 'string' ? error.code : 'ERRORS_UNREADABLE', reason: reason(error) } };\n      }\n    }\n    await answer({ type: 'description', description, errors });\n  }\n} catch (error) {\n  await answer({\n    type: 'failure',\n    code: typeof error?.code === 'string' ? error.code : 'DESCRIBE_FAILED',\n    message: reason(error),\n    ...(typeof error?.plugin === 'string' ? { plugin: error.plugin } : {}),\n  });\n  process.exitCode = 1;\n}\nprocess.disconnect();\n";
+interface CoreDescription {
+    readonly schemaVersion: number;
+    readonly core: string;
+    readonly plugins: readonly DescribedPlugin[];
+    readonly sections: readonly {
+        section: string;
+        plugin: string;
+        value: unknown;
+    }[];
+    readonly unavailable: readonly Unavailable[];
+}
+/** One plugin of core's description; the points only when it declares any (core 0.4.2, D-0130). */
+interface DescribedPlugin {
+    readonly name: string;
+    readonly version: string;
+    readonly described: boolean;
+    readonly contributes?: readonly string[];
+    readonly collects?: readonly string[];
+}
+interface Unavailable {
+    readonly plugin: string;
+    readonly section?: string;
+    readonly code: string;
+    readonly reason: string;
+}
+interface ErrorsRead {
+    readonly file: boolean;
+    readonly definitions?: readonly ErrorDefinition[];
+    readonly failure?: {
+        readonly code: string;
+        readonly reason: string;
+    };
+}
+interface ErrorDefinition {
+    readonly code: string;
+    readonly status: number;
+    readonly message: string;
+    readonly hint?: string;
+}
+export interface DescribeResult {
+    readonly schemaVersion: 1;
+    readonly app: Record<string, unknown>;
+    readonly routes: Record<string, unknown>[];
+    readonly pages: unknown[];
+    readonly jobs: unknown[];
+    readonly schedules: unknown[];
+    readonly errors: ErrorDefinition[];
+    readonly config: {
+        readonly keys: string[];
+        readonly env: Record<string, unknown>[];
+    };
+    readonly db: Record<string, unknown>;
+    readonly unavailable: Unavailable[];
+    readonly warnings?: {
+        code: string;
+        message: string;
+    }[];
+    readonly ms: number;
+}
+export interface DescribeOptions {
+    readonly timeoutMs?: number;
+    /** D-0077 F: also read each connection's tables with dokebi-migrate schema (it connects). */
+    readonly withDb?: boolean;
+    /** Internal input for the mail preview command; only sample data is rendered. */
+    readonly mailPreview?: {
+        readonly name: string;
+        readonly locale?: string;
+    };
+}
+/** The CLI result from core's description and the error definitions. */
+export declare function shapeDescription(name: string | null, description: CoreDescription, errors: ErrorsRead, ms: number, lingered?: boolean): DescribeResult;
+/** `dokebi describe`: loads the project in describe mode and returns the description. */
+export declare function describeProject(root: string, options?: DescribeOptions): Promise<DescribeResult>;
+/**
+ * D-0130: what each module contributes to and who collects it, one line per module point, e.g.
+ * `module points: dokebi-module.notes -> dokebi-mcp:tools (collected by dokebi-mcp)`. A point no
+ * plugin collects says so: its values are dropped (warn POINT_NOT_COLLECTED at start).
+ */
+export declare function modulePointsText(plugins: readonly DescribedPlugin[]): string[];
+/** The short human summary. */
+export declare function describeText(result: DescribeResult): string;
+export {};