@dokebi/cli 0.4.2 → 0.4.27

package/dist/remote-verify.d.ts

@@ -0,0 +1,31 @@
+export interface RemoteCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    /** A failed check that is only a warning (the result stays ok). */
+    readonly warning?: boolean;
+    readonly status?: number;
+    readonly detail: string;
+    readonly ms: number;
+}
+export interface RemoteVerifyResult {
+    readonly ok: boolean;
+    readonly url: string;
+    readonly checks: readonly RemoteCheck[];
+    readonly certificate?: {
+        readonly subject: string;
+        readonly issuer: string;
+        readonly validTo: string;
+        readonly daysLeft: number;
+    };
+}
+export interface RemoteVerifyOptions {
+    readonly root?: string;
+    readonly timeoutMs?: number;
+    /** Trusted certificates besides the system's (tests: a local CA). */
+    readonly ca?: string;
+    /** The port of the plain http check (default 80; tests use a free one). */
+    readonly httpPort?: number;
+}
+/** `dokebi verify --remote` (D-0184 §4). */
+export declare function remoteVerify(input: string, options?: RemoteVerifyOptions): Promise<RemoteVerifyResult>;
+export declare function remoteVerifyText(result: RemoteVerifyResult): string;

package/dist/remote-verify.js

@@ -0,0 +1,204 @@
+// `dokebi verify --remote <https-url>` (D-0184 §4): checks a deployed site from the outside —
+// its TLS certificate, the http to https redirect, the health routes and the security headers.
+// Nothing local runs; the result says which check failed and why.
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { connect } from 'node:tls';
+import { parseConfig } from '@dokebi/config';
+import { readSettings } from './config-show.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+/** Days left below which the certificate check warns (renewal should have happened). */
+const RENEW_DAYS = 14;
+/** HSTS max-age below this many seconds (180 days) is a warning. */
+const HSTS_MIN = 15_552_000;
+function fetchOnce(url, timeoutMs, ca) {
+    return new Promise((resolve, reject) => {
+        const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const request = send(url, {
+            method: 'GET',
+            headers: { 'user-agent': 'dokebi-verify-remote', accept: '*/*' },
+            timeout: timeoutMs,
+            ...(ca === undefined ? {} : { ca }),
+        }, (response) => {
+            // Only the status and headers matter; the body is read to the end and dropped.
+            response.resume();
+            response.once('end', () => resolve({ status: response.statusCode ?? 0, headers: response.headers }));
+            response.once('error', reject);
+        });
+        request.once('timeout', () => request.destroy(new Error(`no answer within ${timeoutMs} ms`)));
+        request.once('error', reject);
+        request.end();
+    });
+}
+function certificateOf(url, timeoutMs, ca) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({
+            host: url.hostname,
+            port: Number(url.port || 443),
+            servername: url.hostname,
+            timeout: timeoutMs,
+            ...(ca === undefined ? {} : { ca }),
+        });
+        socket.once('secureConnect', () => {
+            const certificate = socket.getPeerCertificate();
+            socket.end();
+            if (!socket.authorized)
+                reject(new Error(String(socket.authorizationError)));
+            else
+                resolve(certificate);
+        });
+        socket.once('timeout', () => socket.destroy(new Error(`no TLS handshake within ${timeoutMs} ms`)));
+        socket.once('error', reject);
+    });
+}
+function header(answer, name) {
+    const value = answer.headers[name];
+    return Array.isArray(value) ? value.join(', ') : value;
+}
+/** The health routes of the project's settings when run in one, else the defaults. */
+async function healthRoutes(root) {
+    const defaults = { live: '/health/live', ready: '/health/ready' };
+    if (root === undefined)
+        return defaults;
+    try {
+        const { source } = await readSettings(root);
+        const routes = parseConfig(source).options['dokebi-web']?.healthRoutes;
+        return {
+            live: typeof routes?.live === 'string' ? routes.live : defaults.live,
+            ready: typeof routes?.ready === 'string' ? routes.ready : defaults.ready,
+        };
+    }
+    catch (error) {
+        // Outside a project (or settings that do not parse) the default routes are checked.
+        debug('verify --remote uses the default health routes', { error: describeError(error) });
+        return defaults;
+    }
+}
+/** `dokebi verify --remote` (D-0184 §4). */
+export async function remoteVerify(input, options = {}) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch (cause) {
+        throw new CliError('USAGE', `--remote ${input}: an https URL such as https://shop.example.com`, {
+            phase: 'arguments',
+            cause,
+        });
+    }
+    if (url.protocol !== 'https:' || url.username || url.password)
+        throw new CliError('USAGE', '--remote takes an https URL without credentials', {
+            phase: 'arguments',
+            details: { fix: 'npx dokebi verify --remote https://<domain> --json' },
+        });
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const routes = await healthRoutes(options.root);
+    const checks = [];
+    const timed = async (name, run) => {
+        const started = Date.now();
+        try {
+            checks.push({ name, ...(await run()), ms: Date.now() - started });
+        }
+        catch (error) {
+            checks.push({
+                name,
+                ok: false,
+                detail: describeError(error).split('\n')[0] ?? 'failed',
+                ms: Date.now() - started,
+            });
+        }
+    };
+    let certificate;
+    await timed('tls', async () => {
+        const peer = await certificateOf(url, timeoutMs, options.ca);
+        const daysLeft = Math.floor((Date.parse(peer.valid_to) - Date.now()) / 86_400_000);
+        certificate = {
+            subject: String(peer.subject?.CN ?? ''),
+            issuer: String(peer.issuer?.O ?? peer.issuer?.CN ?? ''),
+            validTo: new Date(peer.valid_to).toISOString(),
+            daysLeft,
+        };
+        return daysLeft < RENEW_DAYS
+            ? {
+                ok: false,
+                warning: true,
+                detail: `the certificate ends in ${daysLeft} days (renewal should have happened)`,
+            }
+            : { ok: true, detail: `valid for ${url.hostname}, ${daysLeft} days left` };
+    });
+    await timed('redirect', async () => {
+        const plain = new URL(url);
+        plain.protocol = 'http:';
+        plain.port = options.httpPort === undefined ? '' : String(options.httpPort);
+        const answer = await fetchOnce(plain, timeoutMs);
+        const location = header(answer, 'location') ?? '';
+        const ok = [301, 302, 307, 308].includes(answer.status) && location.startsWith('https://');
+        return ok
+            ? { ok, status: answer.status, detail: `http answers ${answer.status} to ${location}` }
+            : {
+                ok,
+                warning: true,
+                status: answer.status,
+                detail: `http answers ${answer.status} without a redirect to https`,
+            };
+    });
+    for (const [name, path] of [
+        ['live', routes.live],
+        ['ready', routes.ready],
+    ])
+        await timed(name, async () => {
+            const answer = await fetchOnce(new URL(path, url), timeoutMs, options.ca);
+            return {
+                ok: answer.status === 200,
+                status: answer.status,
+                detail: answer.status === 200 ? `${path} answers 200` : `${path} answers ${answer.status}`,
+            };
+        });
+    await timed('headers', async () => {
+        const answer = await fetchOnce(url, timeoutMs, options.ca);
+        const problems = [];
+        const notes = [];
+        const hsts = header(answer, 'strict-transport-security');
+        const age = Number(/max-age=(\d+)/i.exec(hsts ?? '')?.[1] ?? Number.NaN);
+        if (!hsts)
+            problems.push('no Strict-Transport-Security');
+        else if (!(age >= HSTS_MIN))
+            notes.push(`Strict-Transport-Security max-age ${age} is under 180 days`);
+        if (header(answer, 'x-content-type-options')?.toLowerCase() !== 'nosniff')
+            problems.push('no X-Content-Type-Options: nosniff');
+        // Framing and the referrer policy matter for pages (D-0149 sets them on HTML answers); an
+        // API answer at the URL needs HSTS and nosniff only.
+        const html = /text\/html/i.test(header(answer, 'content-type') ?? '');
+        const csp = header(answer, 'content-security-policy') ?? '';
+        if (html && !header(answer, 'x-frame-options') && !/frame-ancestors/i.test(csp))
+            problems.push('no X-Frame-Options or CSP frame-ancestors');
+        if (html && !header(answer, 'referrer-policy'))
+            notes.push('no Referrer-Policy');
+        if (header(answer, 'x-powered-by'))
+            problems.push('X-Powered-By names the server software');
+        return problems.length
+            ? { ok: false, status: answer.status, detail: [...problems, ...notes].join('; ') }
+            : notes.length
+                ? { ok: false, warning: true, status: answer.status, detail: notes.join('; ') }
+                : {
+                    ok: true,
+                    status: answer.status,
+                    detail: html
+                        ? 'HSTS, nosniff, framing and referrer policy set'
+                        : `HSTS and nosniff set (a ${header(answer, 'content-type')?.split(';')[0] ?? 'non-HTML'} answer: framing and referrer policy not checked)`,
+                };
+    });
+    const ok = checks.every((check) => check.ok || check.warning === true);
+    debug('Remote site checked', {
+        host: url.hostname,
+        ok,
+        failed: checks.filter((check) => !check.ok).map((check) => check.name),
+    });
+    return { ok, url: url.href, checks, ...(certificate ? { certificate } : {}) };
+}
+export function remoteVerifyText(result) {
+    return `${result.checks
+        .map((check) => `${check.ok ? 'ok' : check.warning ? 'WARN' : 'FAIL'} ${check.name} (${check.ms} ms): ${check.detail}`)
+        .join('\n')}\n${result.ok ? `verify --remote ok: ${result.url}` : `verify --remote FAILED: ${result.url}`}\n`;
+}

package/dist/server.d.ts

@@ -103,6 +103,14 @@ export declare function proveInstance(root: string, record: Pick<PidRecord, 'tok
     tried: string[];
     reason?: string;
 }>;
+export declare function checkProject(root: string): Promise<string>;
+/**
+ * R1 T4 review: why a start failed, from the app log of this start only (after its last start
+ * mark): the first record with an error, as `<code>: <first line>` and, when the error has
+ * causes, `… <its last Caused by line>`. A START_FAILED said only "exited with code 1", and its
+ * tail began with an earlier start's lines. Undefined when no record says.
+ */
+export declare function startFailureCause(lines: readonly string[]): string | undefined;
 export interface LogOptions {
     /** Rotate app.log when it would pass this size (default 50 MB). */
     readonly logMaxBytes?: number;
@@ -185,12 +193,43 @@ export declare function stopStarted(root: string, started: Pick<StartResult, 'pi
 export declare function logs(root: string, lines?: number, follow?: boolean, write?: (text: string) => void, signal?: AbortSignal): Promise<void>;
 /** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
 export declare function foreground(root: string): Promise<number>;
+/** The installed version of a package, looked up like Node does (node_modules up the tree). */
+export declare function installedVersion(root: string, name: string): [number, number, number] | undefined;
 /**
  * Development loop: runs the app, restarts it (SIGTERM, drain, start) 300 ms after a change in
- * src/, dokebi.yaml or .env. With a Vite config, Inertia views come from the Vite dev server
- * (HMR, D-0045) when template-inertia supports it, otherwise from watch builds that restart the
- * app. With template-inertia 0.4.0 that Vite is one host process beside the app, shared by every
- * cluster worker and kept across app restarts (D-0045 addendum 3); older ones start it inside the app.
+ * src/, dokebi.yaml or .env (a path whose state differs from the recorded one, see dev-watch.ts).
+ * D-0154: a change of dokebi.yaml alone is first offered to the running app: when every changed
+ * option is reloadable it applies them and keeps running; an invalid file keeps the app as it is;
+ * anything else (an option that needs a restart, an app without reloads) restarts it.
+ * With a Vite config, Inertia views come from the Vite dev server (HMR, D-0045) when
+ * template-inertia supports it, otherwise from watch builds that restart the app. With
+ * template-inertia 0.4.0 that Vite is one host process beside the app, shared by every cluster
+ * worker and kept across app restarts (D-0045 addendum 3); older ones start it inside the app.
  * The first Ctrl+C drains everything; a second one kills.
  */
 export declare function dev(root: string, say: (line: string) => void): Promise<number>;
+/** What `dokebi reload` found and did (D-0154). */
+export interface ReloadResult {
+    readonly running: boolean;
+    readonly pid?: number;
+    /** `applied`, `unchanged`, or `unknown` (no outcome line within the timeout). */
+    readonly outcome?: 'applied' | 'unchanged' | 'unknown';
+    readonly code?: string;
+    /** The configuration revision after the reload, when the app said it. */
+    readonly revision?: number;
+    /** Changed option paths the app named (never values). */
+    readonly paths?: string[];
+    readonly ms?: number;
+    readonly proof?: Proof;
+    /** Who sent SIGHUP: this command, or the app's log writer (a sandbox per command). */
+    readonly via?: 'signal' | 'log-writer';
+    readonly warnings?: string[];
+}
+/**
+ * `dokebi reload` (D-0154): asks the background app to read dokebi.yaml again (SIGHUP to the pid
+ * `start` recorded, proven like `stop`; through its log writer when this shell may not signal
+ * it), then reads its outcome from .dokebi/run/app.log. Options marked reloadable apply without
+ * a restart; an option that needs one (`RELOAD_RESTART_REQUIRED`), an invalid file
+ * (`RELOAD_INVALID`) or a plugin that could not prepare (`RELOAD_FAILED`) change nothing.
+ */
+export declare function reload(root: string, timeoutMs?: number, read?: ProcessReader, kill?: ProcessSignaller): Promise<ReloadResult>;