@dokebi/cli 0.2.4 → 0.4.0

package/dist/registry.d.ts

@@ -0,0 +1,79 @@
+import { type Catalog } from './catalog.js';
+/** npm's built-in default registry. */
+export declare const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+/** Where npm would fetch a package from, as npm itself resolves it in a folder. */
+export interface RegistrySettings {
+    /** Base URL ending with `/`, without credentials (reads are auth-free). */
+    readonly url: string;
+    /** `scope`: `@scope:registry` · `registry`: npm's `registry` · `default`: npm gave none. */
+    readonly from: 'scope' | 'registry' | 'default';
+    /** npm `offline=true`: npm itself would not touch the network, so neither does the CLI. */
+    readonly offline: boolean;
+}
+/**
+ * The registry npm would use for `name` in `cwd`: `@scope:registry` for a scoped package, else
+ * `registry`, from npm's own config resolution (CLI-less: env `npm_config_*`, the project
+ * `.npmrc` (the workspace root's for a member), the user `.npmrc`, the global `npmrc`, npm's
+ * default). The CLI asks npm (`npm config get`, about 0.1 s, no network) instead of reading the
+ * files itself, so precedence, `${VAR}` expansion and `npm_config_userconfig`/`globalconfig`
+ * are exactly npm's. When npm cannot answer, the public registry (npm's default) is used and
+ * the cause goes to the debug log.
+ */
+export declare function registryFor(name: string, cwd?: string): Promise<RegistrySettings>;
+/** `npm config get a b c` prints `a=value` lines (one key alone prints just the value). */
+export declare function parseConfigGet(stdout: string): Map<string, string>;
+/** An http(s) registry URL ending with `/` and without `user:password@`, else undefined. */
+export declare function registryBase(value: string | undefined): string | undefined;
+export type VersionManifest = {
+    dokebi?: {
+        core?: string;
+    };
+    deprecated?: string;
+};
+export type Packument = ({
+    readonly status: 'found';
+    readonly versions: Readonly<Record<string, VersionManifest>>;
+    readonly latest: string | null;
+} | {
+    readonly status: 'missing';
+} | {
+    readonly status: 'offline';
+    readonly error: string;
+}) & {
+    readonly registry: string;
+};
+/**
+ * Reads a package document from the registry npm would use for it in `cwd` (registryFor), with
+ * a plain auth-free GET. `offline` covers network and server errors, and npm `offline=true`.
+ */
+export declare function fetchPackument(name: string, cwd?: string): Promise<Packument>;
+/**
+ * The highest release whose `dokebi.core` range accepts `coreVersion` (a version without the
+ * field counts as compatible). Prereleases are never chosen (semver's `includePrerelease:
+ * false`; one is installed only when named, `add <package>@<version>`), nor a `0.0.0-…`
+ * placeholder. A deprecated version is chosen only when no compatible one is undeprecated.
+ */
+export declare function highestCompatible(packument: {
+    readonly versions: Readonly<Record<string, VersionManifest>>;
+}, coreVersion: string): string | null;
+export interface Resolution {
+    readonly package: string;
+    readonly version: string;
+    readonly source: 'registry' | 'snapshot';
+    readonly core: string;
+    /** The registry the version was read from (npm's, for this package and project). */
+    readonly registry?: string;
+    /** The registry's deprecation message: no undeprecated compatible version exists. */
+    readonly deprecated?: string;
+}
+/**
+ * Picks the version `dokebi add <package>` installs when no version is given: the highest one
+ * compatible with the project core, from the registry npm uses for that package in `cwd`, else
+ * from the CLI snapshot. Throws NOT_PUBLISHED (the registry has no such package) or
+ * NO_COMPATIBLE_VERSION. Returns undefined with an offline marker when neither source knows the
+ * package.
+ */
+export declare function resolveVersion(name: string, coreVersion: string, catalog: Catalog, cwd?: string): Promise<{
+    resolution?: Resolution;
+    offline?: string;
+}>;

package/dist/registry.js

@@ -0,0 +1,212 @@
+import prerelease from 'semver/functions/prerelease.js';
+import rcompare from 'semver/functions/rcompare.js';
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
+import { findPackage } from './catalog.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { runNpm } from './npm-client.js';
+const FETCH_TIMEOUT_MS = 8000;
+const NPM_CONFIG_TIMEOUT_MS = 30_000;
+/** npm's built-in default registry. */
+export const PUBLIC_REGISTRY = 'https://registry.npmjs.org/';
+// One `npm config get` per folder, scope and npm environment for the life of the process.
+const settingsCache = new Map();
+/**
+ * The registry npm would use for `name` in `cwd`: `@scope:registry` for a scoped package, else
+ * `registry`, from npm's own config resolution (CLI-less: env `npm_config_*`, the project
+ * `.npmrc` (the workspace root's for a member), the user `.npmrc`, the global `npmrc`, npm's
+ * default). The CLI asks npm (`npm config get`, about 0.1 s, no network) instead of reading the
+ * files itself, so precedence, `${VAR}` expansion and `npm_config_userconfig`/`globalconfig`
+ * are exactly npm's. When npm cannot answer, the public registry (npm's default) is used and
+ * the cause goes to the debug log.
+ */
+export function registryFor(name, cwd = process.cwd()) {
+    const scope = /^(@[^/]+)\//.exec(name)?.[1];
+    const environment = Object.entries(process.env)
+        .filter(([key]) => key.toLowerCase().startsWith('npm_config_'))
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const key = JSON.stringify([cwd, scope ?? '', process.env.npm_execpath ?? '', environment]);
+    let found = settingsCache.get(key);
+    if (!found) {
+        found = askNpm(cwd, scope);
+        settingsCache.set(key, found);
+    }
+    return found;
+}
+async function askNpm(cwd, scope) {
+    const keys = ['registry', 'offline', ...(scope ? [`${scope}:registry`] : [])];
+    let values;
+    try {
+        const result = await runNpm(cwd, ['config', 'get', ...keys], {
+            timeoutMs: NPM_CONFIG_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0 || result.timedOut) {
+            debug('npm config get failed; using the public registry', {
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                stderr: result.stderr,
+            });
+            return { url: PUBLIC_REGISTRY, from: 'default', offline: false };
+        }
+        values = parseConfigGet(result.stdout);
+    }
+    catch (error) {
+        // npm could not be started: its default registry is what an install would use, too.
+        debug('npm config get could not run; using the public registry', {
+            error: describeError(error),
+        });
+        return { url: PUBLIC_REGISTRY, from: 'default', offline: false };
+    }
+    const offline = values.get('offline') === 'true';
+    const scoped = scope ? registryBase(values.get(`${scope}:registry`)) : undefined;
+    const plain = registryBase(values.get('registry'));
+    const settings = scoped
+        ? { url: scoped, from: 'scope', offline }
+        : plain
+            ? { url: plain, from: 'registry', offline }
+            : { url: PUBLIC_REGISTRY, from: 'default', offline };
+    debug('Registry resolved by npm config', { cwd, scope: scope ?? null, ...settings });
+    return settings;
+}
+/** `npm config get a b c` prints `a=value` lines (one key alone prints just the value). */
+export function parseConfigGet(stdout) {
+    const values = new Map();
+    for (const line of stdout.split(/\r?\n/)) {
+        const at = line.indexOf('=');
+        if (at > 0)
+            values.set(line.slice(0, at).trim(), line.slice(at + 1).trim());
+    }
+    return values;
+}
+/** An http(s) registry URL ending with `/` and without `user:password@`, else undefined. */
+export function registryBase(value) {
+    if (!value || value === 'undefined' || value === 'null')
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        debug('npm registry setting is not a URL; ignored', { error: describeError(error) });
+        return undefined;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return undefined;
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    const text = url.href;
+    return text.endsWith('/') ? text : `${text}/`;
+}
+/**
+ * Reads a package document from the registry npm would use for it in `cwd` (registryFor), with
+ * a plain auth-free GET. `offline` covers network and server errors, and npm `offline=true`.
+ */
+export async function fetchPackument(name, cwd = process.cwd()) {
+    const settings = await registryFor(name, cwd);
+    const registry = settings.url;
+    if (settings.offline) {
+        debug('npm is configured offline; registry not asked', { package: name, registry });
+        return { status: 'offline', error: 'npm offline=true', registry };
+    }
+    const url = `${registry}${name.replace('/', '%2f')}`;
+    const began = performance.now();
+    try {
+        const response = await fetch(url, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        debug('Registry answered', {
+            package: name,
+            registry,
+            status: response.status,
+            ms: Math.round(performance.now() - began),
+        });
+        if (response.status === 404)
+            return { status: 'missing', registry };
+        if (!response.ok)
+            return { status: 'offline', error: `HTTP ${response.status}`, registry };
+        const document = (await response.json());
+        return {
+            status: 'found',
+            versions: document.versions ?? {},
+            latest: document['dist-tags']?.latest ?? null,
+            registry,
+        };
+    }
+    catch (error) {
+        debug('Registry not reachable', { package: name, registry, error: describeError(error) });
+        return {
+            status: 'offline',
+            error: error instanceof Error ? error.message : String(error),
+            registry,
+        };
+    }
+}
+/** `0.0.0-<tag>`: a name-reserving placeholder, never a real release. */
+const PLACEHOLDER = /^0\.0\.0-/;
+/**
+ * The highest release whose `dokebi.core` range accepts `coreVersion` (a version without the
+ * field counts as compatible). Prereleases are never chosen (semver's `includePrerelease:
+ * false`; one is installed only when named, `add <package>@<version>`), nor a `0.0.0-…`
+ * placeholder. A deprecated version is chosen only when no compatible one is undeprecated.
+ */
+export function highestCompatible(packument, coreVersion) {
+    const candidates = Object.entries(packument.versions)
+        .filter(([version, manifest]) => {
+        if (!valid(version) || prerelease(version) || PLACEHOLDER.test(version))
+            return false;
+        const range = manifest.dokebi?.core;
+        return range === undefined || satisfies(coreVersion, range);
+    })
+        .sort(([a], [b]) => rcompare(a, b));
+    return candidates.find(([, manifest]) => !manifest.deprecated)?.[0] ?? candidates[0]?.[0] ?? null;
+}
+/**
+ * Picks the version `dokebi add <package>` installs when no version is given: the highest one
+ * compatible with the project core, from the registry npm uses for that package in `cwd`, else
+ * from the CLI snapshot. Throws NOT_PUBLISHED (the registry has no such package) or
+ * NO_COMPATIBLE_VERSION. Returns undefined with an offline marker when neither source knows the
+ * package.
+ */
+export async function resolveVersion(name, coreVersion, catalog, cwd = process.cwd()) {
+    const found = await fetchPackument(name, cwd);
+    if (found.status === 'missing')
+        throw new CliError('NOT_PUBLISHED', `${name} is not published on the registry`, {
+            details: { package: name, registry: found.registry },
+            phase: 'install',
+        });
+    if (found.status === 'found') {
+        const version = highestCompatible(found, coreVersion);
+        if (!version)
+            throw new CliError('NO_COMPATIBLE_VERSION', `No version of ${name} supports @dokebi/core ${coreVersion}`, {
+                details: {
+                    package: name,
+                    core: coreVersion,
+                    latest: found.latest,
+                    registry: found.registry,
+                },
+                phase: 'install',
+            });
+        const deprecated = found.versions[version]?.deprecated;
+        return {
+            resolution: {
+                package: name,
+                version,
+                source: 'registry',
+                core: coreVersion,
+                registry: found.registry,
+                ...(deprecated ? { deprecated } : {}),
+            },
+        };
+    }
+    const known = findPackage(catalog, name);
+    if (known && known.package === name && (!known.core || satisfies(coreVersion, known.core)))
+        return {
+            resolution: { package: name, version: known.version, source: 'snapshot', core: coreVersion },
+            offline: found.error,
+        };
+    return { offline: found.error };
+}

package/dist/rotating-log.d.ts

@@ -9,6 +9,18 @@ export declare class LineBuffer {
     /** The unfinished end (a line without its newline yet), emptied. */
     take(): Buffer;
 }
+/**
+ * The writer's output path (D-0053): whole lines of stdout and stderr go to `log`, and `onStarted`
+ * runs once, right **after** the data holding `marker` (the start line) was written. The CLI reads
+ * app.log as soon as it hears `ready` (it counts on the start line and the lines before it being
+ * there, and parses the listening URLs from them), so the notice must never overtake the write.
+ * Sending it first raced a slow write — a busy machine hands the writer the whole startup output in
+ * one chunk, and a rotation that fails while writing it reports the failure before the rest is
+ * appended; `dokebi start` then saw only the lines that fitted before the limit.
+ */
+export declare function forwardOutput(log: {
+    write(data: Buffer): void;
+}, marker: string, onStarted: () => void): (data: Buffer) => void;
 export declare class RotatingLog {
     #private;
     readonly file: string;

package/dist/rotating-log.js

@@ -41,6 +41,25 @@ export class LineBuffer {
         return rest;
     }
 }
+/**
+ * The writer's output path (D-0053): whole lines of stdout and stderr go to `log`, and `onStarted`
+ * runs once, right **after** the data holding `marker` (the start line) was written. The CLI reads
+ * app.log as soon as it hears `ready` (it counts on the start line and the lines before it being
+ * there, and parses the listening URLs from them), so the notice must never overtake the write.
+ * Sending it first raced a slow write — a busy machine hands the writer the whole startup output in
+ * one chunk, and a rotation that fails while writing it reports the failure before the rest is
+ * appended; `dokebi start` then saw only the lines that fitted before the limit.
+ */
+export function forwardOutput(log, marker, onStarted) {
+    let started = false;
+    return (data) => {
+        log.write(data);
+        if (started || !data.includes(marker))
+            return;
+        started = true;
+        onStarted();
+    };
+}
 export class RotatingLog {
     file;
     maxBytes;

package/dist/server.d.ts

@@ -1,3 +1,4 @@
+import { type AppHosts } from './app-urls.js';
 /** Rotation defaults and limits (D-0053): `--log-max-mb`, `--log-files`. */
 export declare const LOG_LIMITS: {
     readonly maxMb: {
@@ -20,7 +21,20 @@ export interface PidRecord {
     readonly logWriter?: number;
     readonly logMaxBytes?: number;
     readonly logFiles?: number;
+    /** The app's DOKEBI_INSTANCE_TOKEN (D-0073); absent in pid files of older CLIs. */
+    readonly token?: string;
+    /** Where the app answered (the web listening line), for the proof without `ps`. */
+    readonly urls?: string[];
+    /** The log writer's loopback control port (D-0073 addendum); absent when it could not listen. */
+    readonly control?: number;
 }
+/** How a pid was shown to be this project's app (ServerStatus.proof). */
+export type Proof = 'process' | 'http' | 'log-writer';
+/**
+ * Sends a signal like `process.kill` (signal 0 tests the pid). Tests replace it to act as a
+ * sandbox that refuses signals (EPERM).
+ */
+export type ProcessSignaller = (pid: number, signal: NodeJS.Signals | 0) => void;
 export interface LogFile {
     readonly file: string;
     readonly bytes: number;
@@ -33,6 +47,12 @@ export interface ServerStatus {
     readonly rssMb?: number;
     /** A pid file was left by a process that is gone (crashed or killed); it was removed. */
     readonly stale?: boolean;
+    /**
+     * How the recorded pid was shown to be this project's app: `process` (ps or /proc: command and
+     * start time), `log-writer` (no process information; the app's log writer proved the instance
+     * token on its control socket) or `http` (the app answered the instance challenge).
+     */
+    readonly proof?: Proof;
     readonly log: string;
     /** app.log and its rotated files, newest first. */
     readonly logFiles: LogFile[];
@@ -44,7 +64,38 @@ export interface ServerStatus {
     /** The writer's own diagnostics, when it wrote any. */
     readonly logWriterLog?: string;
 }
-export declare function status(root: string): Promise<ServerStatus>;
+export interface ProcessInfo {
+    startedAt: number;
+    rssKb: number;
+    command: string;
+}
+/**
+ * Reads a process: undefined when there is no such process. When the information cannot be
+ * read (no `ps`, a sandbox, /proc unreadable) it throws `PROCESS_INFO_FAILED`: the process may
+ * be alive, so callers never treat that as a stale pid file.
+ */
+export type ProcessReader = (pid: number) => Promise<ProcessInfo | undefined>;
+export declare function status(root: string, 
+/** Tests replace how a process is read; the CLI uses ps (/proc on Linux). */
+read?: ProcessReader, 
+/** Tests replace how a process is signalled; the CLI uses process.kill. */
+kill?: ProcessSignaller): Promise<ServerStatus>;
+/** The variable `start` gives the app (D-0073); @dokebi/web answers the challenge with it. */
+export declare const INSTANCE_TOKEN_ENV = "DOKEBI_INSTANCE_TOKEN";
+/** The challenge request header and the answer response header of @dokebi/web. */
+export declare const INSTANCE_HEADER = "x-dokebi-instance";
+/** The answer to a challenge: base64url HMAC-SHA256 keyed with the instance token. */
+export declare function instanceAnswer(token: string, challenge: string): string;
+/**
+ * Whether the app at the recorded address knows the record's instance token (D-0073): a random
+ * challenge must come back as HMAC-SHA256(token, challenge). The token never goes on the wire.
+ */
+export declare function proveInstance(root: string, record: Pick<PidRecord, 'token' | 'urls'>, timeoutMs?: number): Promise<{
+    proven: boolean;
+    url?: string;
+    tried: string[];
+    reason?: string;
+}>;
 export interface LogOptions {
     /** Rotate app.log when it would pass this size (default 50 MB). */
     readonly logMaxBytes?: number;
@@ -60,16 +111,35 @@ export interface StartResult {
     readonly logFiles: number;
     /** False when the process is alive but never logged the start line within the wait. */
     readonly ready: boolean;
+    /**
+     * Where the app answers (AI-M03): with @dokebi/app, `<scheme>://<domain>:<port>` for each
+     * configured loopback domain (`localhost`, `*.localhost`, `127.x.x.x`); without it, `listen`.
+     */
+    readonly urls: string[];
+    /** Addresses from the web plugin's listening log line (empty when it logged none). */
+    readonly listen: string[];
     readonly ms: number;
     readonly warnings: string[];
 }
 export interface StartOptions extends LogOptions {
     /** How long to wait for the start line (default 10000 ms). */
     readonly waitMs?: number;
+    /** Extra environment for the app (verify passes its instance token, D-0065 §11). */
+    readonly env?: Readonly<Record<string, string>>;
 }
 export declare function start(root: string, options?: StartOptions, 
 /** Tests replace the project inspection; the CLI always inspects. */
 check?: (root: string) => Promise<string>): Promise<StartResult>;
+/**
+ * HTTP URLs from `Web server listening` log lines (D-0065): `address`, `addresses` or `urls`
+ * fields as strings (`http://…`) or `{ address, port }` objects. Unknown shapes are skipped.
+ */
+export declare function listeningUrls(text: string): string[];
+/**
+ * The app host settings for the shown URLs; when they cannot be read the listening addresses are
+ * shown instead (the app already runs: this is no reason to fail the command).
+ */
+export declare function appHostsOrNone(root: string): Promise<AppHosts>;
 export interface StopResult {
     readonly stopped: boolean;
     readonly pid?: number;
@@ -78,8 +148,26 @@ export interface StopResult {
     readonly stale?: boolean;
     /** Set when the log writer was still running 5 s after the app stopped. */
     readonly warnings?: string[];
+    /** How the pid was shown to be this project's app (see ServerStatus.proof). */
+    readonly proof?: Proof;
+    /**
+     * Who sent the stop signals: `signal` (this command) or `log-writer` (the app's log writer on
+     * request, when this shell may not signal the app: an agent sandbox per command).
+     */
+    readonly via?: 'signal' | 'log-writer';
 }
-export declare function stop(root: string, timeoutMs?: number, force?: boolean): Promise<StopResult>;
+export declare function stop(root: string, timeoutMs?: number, force?: boolean, 
+/** Tests replace how a process is read; the CLI uses ps (/proc on Linux). */
+read?: ProcessReader, 
+/** Tests replace how a process is signalled; the CLI uses process.kill. */
+kill?: ProcessSignaller): Promise<StopResult>;
+/**
+ * Stops the app this CLI run started (`start`'s result), without `ps` (see the file comment):
+ * SIGTERM, wait for the drain, SIGKILL after `timeoutMs` when `force`, then the pid file (when it
+ * still names this process) and a wait for the log writer. An app that already exited by itself
+ * is `{ stopped: false, stale: true }`.
+ */
+export declare function stopStarted(root: string, started: Pick<StartResult, 'pid' | 'logWriter'>, timeoutMs?: number, force?: boolean): Promise<StopResult>;
 /**
  * Prints the last `lines` lines (across app.log and its rotated files); with `follow`, keeps
  * printing what is appended until SIGINT (or `signal`), following app.log across rotations.
@@ -93,7 +181,9 @@ export declare function foreground(root: string): Promise<number>;
 /**
  * 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
- * inside the app (HMR, D-0045) when template-inertia supports it, otherwise from watch builds
- * that restart the app. The first Ctrl+C drains everything; a second one kills.
+ * (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>;