@dokebi/cli 0.4.1 → 0.4.2

package/dist/transaction.js

@@ -1,8 +1,39 @@
-import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { link, lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { hash as hashing } from '@dokebi/core/libraries';
 import { debug, debugEnabled, describeError, reportError } from './diagnostics.js';
 import { CliError } from './errors.js';
-import { exists, fingerprint, json, securePath } from './filesystem.js';
+import { exists, fingerprint, hash, json, securePath } from './filesystem.js';
+/**
+ * What is at `path` now, without following a symlink: null when nothing is there, `file:<sha256>`
+ * for a file, `directory:<dev>:<ino>` for a folder (its identity: a folder's content is not
+ * hashed), `symlink` or `other`.
+ */
+async function observe(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        return 'symlink';
+    if (stat.isDirectory())
+        return `directory:${stat.dev}:${stat.ino}`;
+    if (!stat.isFile())
+        return 'other';
+    return `file:${await hashing.sha256File(path)}`;
+}
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EMLINK', 'EXDEV']);
+/** Why `now` is not the `installed` fingerprint (both as `observe` writes them). */
+function differs(installed, now) {
+    if (now === 'symlink')
+        return 'symlink';
+    return installed?.startsWith('file:') && now.startsWith('file:') ? 'modified' : 'replaced';
+}
 export class Transaction {
     root;
     directory;
@@ -70,13 +101,17 @@ export class Transaction {
     async write(path, content) {
         const source = join(this.directory, `new-${this.#changes.length}`);
         await writeFile(source, content, { mode: 0o600 });
-        await this.replace(path, source);
+        await this.#add(path, source, `file:${hash(content)}`);
     }
+    /** Puts `source` (a file or folder) at `path` on commit; without `source`, removes `path`. */
     async replace(path, source) {
+        await this.#add(path, source);
+    }
+    async #add(path, source, installs) {
         if (this.#changes.some((change) => change.path === path))
             throw new CliError('DUPLICATE_CHANGE', path);
         await this.capture(path);
-        this.#changes.push(source === undefined ? { path } : { path, source });
+        this.#changes.push(source === undefined ? { path } : installs ? { path, source, installs } : { path, source });
     }
     get paths() {
         return this.#changes.map((change) => change.path);
@@ -84,6 +119,11 @@ export class Transaction {
     /**
      * Applies every change; `afterApply` runs once they are all in place, and when it fails the
      * changes are rolled back like a failed apply (D-0035: the workspace npm install).
+     *
+     * The rollback only undoes what is still this commit's own (ISSUE-0006 A06): `afterApply` can
+     * run for minutes while the user edits files. A path that is no longer what this commit put
+     * there (or, for a removed path, where something appeared) is left as it is, its original stays
+     * in the transaction folder, and the commit ends with RECOVERY_REQUIRED naming those paths.
      */
     async commit(beforeApply, afterApply) {
         for (const [path, expected] of this.#snapshots) {
@@ -91,13 +131,20 @@ export class Transaction {
                 throw new CliError('CONCURRENT_CHANGE', `File changed while planning: ${path}`);
             }
         }
-        const journal = this.#changes.map((change, index) => ({
-            ...change,
-            backup: join(this.directory, `old-${index}`),
-            existed: this.#snapshots.get(change.path) !== null,
-            backedUp: false,
-            installed: false,
-        }));
+        const journal = [];
+        for (const [index, change] of this.#changes.entries()) {
+            // What this change installs, to recognise it again in a rollback: a written file's hash, a
+            // staged file's hash or a staged folder's identity (node_modules).
+            const installs = change.installs ?? (change.source ? await observe(change.source) : null) ?? undefined;
+            journal.push({
+                ...change,
+                ...(installs ? { installs } : {}),
+                backup: join(this.directory, `old-${index}`),
+                existed: this.#snapshots.get(change.path) !== null,
+                backedUp: false,
+                installed: false,
+            });
+        }
         await writeFile(join(this.directory, 'journal.json'), json(journal));
         try {
             for (const [index, change] of journal.entries()) {
@@ -134,39 +181,140 @@ export class Transaction {
                     changes: journal.length,
                     error: describeError(cause),
                 });
-            const failures = [];
-            for (const change of [...journal].reverse()) {
+            await this.#rollback(journal, cause);
+        }
+    }
+    async #rollback(journal, cause) {
+        const failures = [];
+        const conflicts = [];
+        for (const [index, change] of [...journal.entries()].reverse()) {
+            try {
+                const conflict = await this.#undo(change, index);
+                if (conflict) {
+                    debug('Rollback kept a path changed during the commit', { ...conflict });
+                    conflicts.push(conflict);
+                }
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length || conflicts.length) {
+            this.#keep = true;
+            const directory = relative(this.root, this.directory);
+            const kept = conflicts.length
+                ? `kept ${conflicts.length} path(s) changed during the operation: ${conflicts
+                    .map((item) => `${item.path} (${item.reason})`)
+                    .join(', ')}; `
+                : '';
+            const failed = failures.length ? `${failures.length} step(s) failed; ` : '';
+            throw new CliError('RECOVERY_REQUIRED', `Rollback ${kept}${failed}preserve ${directory} and .dokebi/lock`, {
+                cause: failures.length ? new AggregateError([cause, ...failures]) : cause,
+                phase: 'commit',
+                details: { conflicts, transaction: directory },
+            });
+        }
+        throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
+    }
+    /**
+     * Undoes one change unless the path is no longer this commit's own: then leaves it and says
+     * why. The look and the removal cannot be one atomic step; the window is kept to a rename
+     * (see `#undo`'s move-aside) and documented in docs/cli/README.md.
+     */
+    async #undo(change, index) {
+        const backup = change.backedUp ? { backup: relative(this.root, change.backup) } : {};
+        let target;
+        try {
+            // The parent folders, never following a symlink; the path itself is looked at below.
+            const parent = dirname(change.path);
+            const folder = parent === '.' ? this.root : await securePath(this.root, parent);
+            target = join(folder, basename(change.path));
+        }
+        catch (error) {
+            const code = error instanceof CliError ? error.code : undefined;
+            if (code !== 'UNSAFE_PATH' && code !== 'PATH_CONFLICT')
+                throw error;
+            return {
+                path: change.path,
+                reason: code === 'UNSAFE_PATH' ? 'unsafe-path' : 'path-conflict',
+                ...backup,
+            };
+        }
+        if (change.kind === 'directory') {
+            if (!change.installed)
+                return undefined;
+            try {
+                // rmdir removes only an empty folder and never follows a symlink.
+                await rmdir(target);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ENOENT')
+                    return undefined;
+                if (code === 'ENOTEMPTY' || code === 'EEXIST')
+                    return { path: change.path, reason: 'not-empty' };
+                if (code === 'ENOTDIR')
+                    return { path: change.path, reason: 'replaced' };
+                throw error;
+            }
+            return undefined;
+        }
+        if (change.installed) {
+            const now = await observe(target);
+            if (now !== null) {
+                if (now !== change.installs)
+                    return { path: change.path, reason: differs(change.installs, now), ...backup };
+                // Move it aside (atomic), then look again: an edit between the look and the move is
+                // found here and put back, never deleted.
+                const aside = join(this.directory, `rollback-${index}`);
                 try {
-                    const target = await securePath(this.root, change.path);
-                    if (change.kind === 'directory') {
-                        if (change.installed) {
-                            try {
-                                await rmdir(target);
-                            }
-                            catch (error) {
-                                if (error.code !== 'ENOENT')
-                                    throw error;
-                            }
-                        }
-                        continue;
-                    }
-                    if (change.installed)
-                        await rm(target, { recursive: true, force: true });
-                    if (change.backedUp)
-                        await rename(change.backup, target);
+                    await rename(target, aside);
                 }
                 catch (error) {
-                    failures.push(error);
+                    if (error.code !== 'ENOENT')
+                        throw error;
                 }
+                const moved = await observe(aside);
+                if (moved !== null && moved !== change.installs) {
+                    const restored = await this.#place(aside, target);
+                    return {
+                        path: change.path,
+                        reason: differs(change.installs, moved),
+                        ...backup,
+                        ...(restored ? {} : { kept: relative(this.root, aside) }),
+                    };
+                }
+                if (moved !== null)
+                    await rm(aside, { recursive: true, force: true });
             }
-            if (failures.length) {
-                this.#keep = true;
-                throw new CliError('RECOVERY_REQUIRED', `Rollback failed; preserve ${this.directory} and .dokebi/lock`, {
-                    cause: new AggregateError([cause, ...failures]),
-                });
-            }
-            throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
         }
+        if (change.backedUp && !(await this.#place(change.backup, target)))
+            return { path: change.path, reason: 'created', ...backup };
+        return undefined;
+    }
+    /**
+     * Moves `from` to `to` without replacing anything at `to`: false when something is there. A
+     * file goes by link + unlink (link fails on an existing name); a folder (or a file system
+     * without hard links) by rename after checking `to` is free, which leaves a tiny window.
+     */
+    async #place(from, to) {
+        try {
+            await link(from, to);
+            await unlink(from);
+            return true;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (code === 'EEXIST')
+                return false;
+            if (!LINK_UNSUPPORTED.has(code))
+                throw error;
+            debug('Rollback restores by rename (no hard link)', { path: to, code });
+        }
+        if ((await observe(to)) !== null)
+            return false;
+        await rename(from, to);
+        return true;
     }
     async close() {
         if (this.#keep)

package/dist/verify.d.ts

@@ -46,17 +46,26 @@ export interface HttpProbe {
     readonly ok: boolean;
     /** `other`: an answer without this run's token header — another server on the port. */
     readonly instance?: 'ours' | 'other';
+    /**
+     * The identity probe (no readiness route and no app domain): `GET /` passes with any status
+     * below 500 that carries this run's header.
+     */
+    readonly identity?: true;
     readonly error?: string;
 }
 /**
  * The HTTP check of verify: GET the readiness path, then `/` of each app domain, at `base`. An
  * answer counts only when it carries `token` in the x-dokebi-verify header (the instance verify
  * started); anything else is retried like a failed request and then reported FOREIGN_SERVER.
+ * With neither a readiness path (`healthRoutes: false`) nor an app domain, one identity probe
+ * runs instead (ISSUE-0006 A08: no request at all used to pass): `GET /`, which passes with any
+ * status below 500 that carries the token, a 404 included (the app may have no route at `/`).
+ * Each request must complete within `timeoutMs` (ISSUE-0006 A09).
  */
 export declare function httpChecks(base: string, paths: {
     ready: string | null;
     domains: readonly string[];
-}, token: string, delayMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
+}, token: string, delayMs?: number, timeoutMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
 export declare function verify(root: string, options?: {
     waitMs?: number;
 }): Promise<VerifyResult>;

package/dist/verify.js

@@ -61,10 +61,31 @@ export async function npmScript(root, script, timeoutMs) {
 export const VERIFY_TOKEN_ENV = 'DOKEBI_VERIFY_TOKEN';
 /** The response header @dokebi/web answers with when that variable is set. */
 export const VERIFY_HEADER = 'x-dokebi-verify';
-/** GET with a Host header (fetch cannot set one). */
+/**
+ * GET with a Host header (fetch cannot set one). Settles once: with the answer when the body
+ * ended, or with an error when the request fails, the response is aborted or its connection
+ * closes before the end (ISSUE-0006 A09), or nothing complete came within `timeoutMs` in all
+ * (the socket timeout alone never fires for a server that keeps trickling bytes).
+ */
 function get(url, host, timeoutMs = 5000) {
     return new Promise((resolve, reject) => {
         const target = new URL(url);
+        let settled = false;
+        const finish = (error, answer) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            if (error) {
+                // Frees the socket of a response that will never complete.
+                if (!req.destroyed)
+                    req.destroy();
+                reject(error);
+            }
+            else
+                resolve(answer);
+        };
+        const failed = (error) => finish(error);
         const req = request({
             host: target.hostname.replace(/^\[|\]$/g, ''),
             port: target.port,
@@ -73,14 +94,23 @@ function get(url, host, timeoutMs = 5000) {
             timeout: timeoutMs,
         }, (response) => {
             response.resume();
-            response.once('end', () => resolve({
+            response.once('end', () => finish(undefined, {
                 status: response.statusCode ?? 0,
                 type: String(response.headers['content-type'] ?? ''),
                 instance: response.headers[VERIFY_HEADER],
             }));
+            response.once('aborted', () => finish(new Error('The response was aborted')));
+            // Error listeners stay after settling: a late error (the destroy below) is then ignored
+            // by `finish` instead of being an unhandled 'error' event.
+            response.on('error', failed);
+            response.once('close', () => {
+                if (!response.complete)
+                    finish(new Error('The connection closed before the response ended'));
+            });
         });
+        const deadline = setTimeout(() => finish(new Error(`No complete answer within ${timeoutMs} ms`)), timeoutMs);
         req.once('timeout', () => req.destroy(new Error(`No answer within ${timeoutMs} ms`)));
-        req.once('error', reject);
+        req.on('error', failed);
         req.end();
     });
 }
@@ -123,18 +153,30 @@ async function settings(root) {
  * The HTTP check of verify: GET the readiness path, then `/` of each app domain, at `base`. An
  * answer counts only when it carries `token` in the x-dokebi-verify header (the instance verify
  * started); anything else is retried like a failed request and then reported FOREIGN_SERVER.
+ * With neither a readiness path (`healthRoutes: false`) nor an app domain, one identity probe
+ * runs instead (ISSUE-0006 A08: no request at all used to pass): `GET /`, which passes with any
+ * status below 500 that carries the token, a 404 included (the app may have no route at `/`).
+ * Each request must complete within `timeoutMs` (ISSUE-0006 A09).
  */
-export async function httpChecks(base, paths, token, delayMs = 250) {
+export async function httpChecks(base, paths, token, delayMs = 250, timeoutMs = 5000) {
     const requests = [];
-    const probe = async (path, host, attempts) => {
+    const probe = async (path, host, attempts, identity = false) => {
         const url = `${base}${path}`;
+        const kind = identity ? { identity: true } : {};
         for (let attempt = 1;; attempt++) {
             try {
-                const answer = await get(url, host);
+                const answer = await get(url, host, timeoutMs);
                 const instance = answer.instance === token ? 'ours' : 'other';
-                const ok = answer.status >= 200 && answer.status < 400 && instance === 'ours';
+                const ok = answer.status >= 200 && answer.status < (identity ? 500 : 400) && instance === 'ours';
                 if (ok || attempt >= attempts) {
-                    requests.push({ url, ...(host ? { host } : {}), status: answer.status, ok, instance });
+                    requests.push({
+                        url,
+                        ...(host ? { host } : {}),
+                        status: answer.status,
+                        ok,
+                        instance,
+                        ...kind,
+                    });
                     return;
                 }
                 if (instance === 'other')
@@ -151,6 +193,7 @@ export async function httpChecks(base, paths, token, delayMs = 250) {
                         status: 0,
                         ok: false,
                         error: error instanceof Error ? error.message : String(error),
+                        ...kind,
                     });
                     return;
                 }
@@ -163,6 +206,10 @@ export async function httpChecks(base, paths, token, delayMs = 250) {
         await probe(paths.ready, undefined, 20);
     for (const domain of paths.domains)
         await probe('/', domain, 4);
+    if (!paths.ready && !paths.domains.length) {
+        debug('verify: no readiness route and no app domain; probing GET / for this run', { base });
+        await probe('/', undefined, 20, true);
+    }
     const failed = requests.filter((item) => !item.ok);
     const foreign = failed.filter((item) => item.instance === 'other');
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Project scaffolding, plugin catalog, recipes, install and verification CLI for Dokebi.",
   "keywords": [
     "dokebi",