@rse/ase 2.0.1 → 2.0.3

package/dst/ase-lib-daemon-cli.js

@@ -5,9 +5,122 @@
 */
 import path from "node:path";
 import fs from "node:fs";
+import net from "node:net";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
-import { Service } from "./ase-service.js";
+import { Tail } from "tail";
+/*  the loopback host to probe the ports on, the range and the number of attempts
+    of the random port allocation, and the bounds of the append-only log files:
+    maximum tolerated size and number of tail lines surviving a trim  */
+const HOST = "127.0.0.1";
+const PORT_MIN = 42000;
+const PORT_MAX = 44000;
+const PORT_TRIES = 20;
+const LOG_MAX_SIZE = 1024 * 1024;
+const LOG_KEEP_LINES = 2000;
+/*  reusable functionality: port allocation and log file handling of the background processes  */
+export class Daemon {
+    /*  try binding a single candidate port to verify availability  */
+    static tryBind(port) {
+        return new Promise((resolve) => {
+            const s = net.createServer();
+            s.once("error", () => {
+                resolve(false);
+            });
+            s.once("listening", () => {
+                s.close(() => resolve(true));
+            });
+            s.listen(port, HOST);
+        });
+    }
+    /*  allocate the preferred port, if given and available,
+        else a fresh random port in PORT_MIN..PORT_MAX  */
+    static async allocatePort(pref = null) {
+        if (pref !== null && await Daemon.tryBind(pref))
+            return pref;
+        for (let i = 0; i < PORT_TRIES; i++) {
+            const p = PORT_MIN + Math.floor(Math.random() * (PORT_MAX - PORT_MIN + 1));
+            if (await Daemon.tryBind(p))
+                return p;
+        }
+        throw new Error(`failed to allocate a port in ${PORT_MIN}..${PORT_MAX} after ${PORT_TRIES} attempts`);
+    }
+    /*  trim the log file down to its tail if it grew beyond the size limit  */
+    static trimLog(logFile) {
+        try {
+            if (!fs.existsSync(logFile) || fs.statSync(logFile).size <= LOG_MAX_SIZE)
+                return;
+            const tail = Daemon.readLogTail(logFile, LOG_KEEP_LINES);
+            fs.writeFileSync(logFile, tail.length > 0 ? `${tail}\n` : "");
+        }
+        catch {
+            /*  intentionally ignore all trimming errors, as a
+                non-trimmable log file must never block the service  */
+        }
+    }
+    /*  read the last N non-empty lines of a log file for diagnostics  */
+    static readLogTail(logFile, lines) {
+        let fd = null;
+        try {
+            fd = fs.openSync(logFile, "r");
+            const size = fs.fstatSync(fd).size;
+            const CHUNK = 8192;
+            const chunks = [];
+            let pos = size;
+            let count = 0;
+            while (pos > 0 && count <= lines) {
+                const n = Math.min(CHUNK, pos);
+                const buf = Buffer.alloc(n);
+                pos -= n;
+                fs.readSync(fd, buf, 0, n, pos);
+                chunks.unshift(buf);
+                for (let i = 0; i < n; i++)
+                    if (buf[i] === 10)
+                        count++;
+            }
+            /*  decode once after re-assembly to avoid splitting
+                multi-byte UTF-8 sequences at chunk boundaries  */
+            const all = Buffer.concat(chunks).toString("utf8")
+                .split("\n").filter((l) => l.length > 0);
+            return all.slice(-lines).join("\n");
+        }
+        catch {
+            return "";
+        }
+        finally {
+            if (fd !== null)
+                fs.closeSync(fd);
+        }
+    }
+    /*  show a log file on stdout, either completely or its last <lines> lines only, and
+        optionally follow it for newly appended lines (default: the last 10 lines first),
+        where each line is passed through <transform> (e.g. to colorize parts of it)  */
+    static async showLog(logFile, opts, transform = (line) => line) {
+        const lines = opts.lines !== undefined ? Number(opts.lines) : null;
+        if (lines !== null && (!Number.isInteger(lines) || lines < 1))
+            throw new Error(`invalid number of lines: ${opts.lines}`);
+        if (!fs.existsSync(logFile))
+            return 0;
+        if (opts.follow) {
+            /*  follow until interrupted (on log trimming,
+                "tail" continues at the new end of the file)  */
+            const tail = new Tail(logFile, { nLines: lines ?? 10 });
+            tail.on("line", (line) => {
+                process.stdout.write(`${transform(line)}\n`);
+            });
+            return await new Promise((_resolve, reject) => {
+                tail.on("error", (err) => {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                });
+            });
+        }
+        const text = lines !== null ?
+            Daemon.readLogTail(logFile, lines) :
+            fs.readFileSync(logFile, "utf8").replace(/\n$/, "");
+        process.stdout.write(text.length > 0 ? `${text.split("\n").map(transform).join("\n")}\n` : "");
+        return 0;
+    }
+}
 /*  the CLI command group managing a long-running process (a server, an agent, or a fleet
     of them) in the background or in the foreground: it registers the command group, spawns
     the process detached into its log file, awaits its startup, checks whether it is alive,
@@ -47,14 +160,14 @@ export class DaemonCommand {
                     "(not yet run in the background, as one run in the foreground logs to the terminal)");
                 return;
             }
-            process.exitCode = await Service.showLog(file, opts, transform);
+            process.exitCode = await Daemon.showLog(file, opts, transform);
         });
     }
     /*  spawn the CLI with the arguments <args> detached, with the additional
         environment <env>, logging into the (trimmed) log file <logFile>  */
     spawnDetached(args, env, logFile) {
         fs.mkdirSync(path.dirname(logFile), { recursive: true });
-        Service.trimLog(logFile);
+        Daemon.trimLog(logFile);
         const fd = fs.openSync(logFile, "a");
         const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
         const child = spawn(process.execPath, [entry, ...args], {
@@ -95,7 +208,7 @@ export class DaemonCommand {
         if (failure === null)
             return;
         const reason = `${this.label}: ${failure}`;
-        const tail = Service.readLogTail(logFile, 20);
+        const tail = Daemon.readLogTail(logFile, 20);
         throw new Error(tail.length > 0 ? `${reason}\n---- ${logFile} (tail) ----\n${tail}` : reason);
     }
     /*  check whether a process is still alive  */

package/dst/ase-lib-server-cli.js

@@ -13,8 +13,8 @@ import { isSeq, isScalar } from "yaml";
 import { Config } from "./ase-config-core.js";
 import { parseScope } from "./ase-config-scope.js";
 import { isLogLevel } from "./ase-lib-log.js";
-import { Service } from "./ase-service.js";
-import { DaemonCommand } from "./ase-lib-daemon-cli.js";
+import { writeStdout } from "./ase-lib-stdio.js";
+import { Daemon, DaemonCommand } from "./ase-lib-daemon-cli.js";
 import { urlHost, isLoopback, serverHeader } from "./ase-lib-server-bind.js";
 /*  the defaults  */
 export const DEFAULT_ADDRESS = "127.0.0.1";
@@ -44,7 +44,7 @@ export const configuredTls = (cfg, prefix) => {
             if (isLocal(new URL(url.value).hostname.replace(/^\[|\]$/g, "")))
                 return { cert: null, key: null };
         }
-        catch (_err) {
+        catch {
             /*  an invalid URL is reported by its users  */
         }
     }
@@ -270,7 +270,7 @@ export class ServerCommand extends DaemonCommand {
             child.kill("SIGTERM");
             child.unref();
         }
-        const tail = Service.readLogTail(logFile, 20);
+        const tail = Daemon.readLogTail(logFile, 20);
         const reason = exited ?
             `${this.label}: server exited during startup (code ${exitCode})` :
             probed === "foreign" ?
@@ -351,7 +351,7 @@ export class ServerCommand extends DaemonCommand {
             /*  re-allocate a configured port held by a foreign service  */
             if (foreign)
                 this.log.write("warning", `${this.label}: configured port ${port} in use by foreign service, re-allocating`);
-            port = await Service.allocatePort();
+            port = await Daemon.allocatePort();
         }
         let token = opts.token ?? process.env[this.env("TOKEN")] ?? ctx.token;
         if (token === undefined || token === null || token === "")
@@ -381,26 +381,26 @@ export class ServerCommand extends DaemonCommand {
     async doStatus() {
         const ctx = this.loadContext();
         if (ctx.port === null) {
-            process.stdout.write(`${this.label}: not running (no port configured)\n`);
+            await writeStdout(`${this.label}: not running (no port configured)\n`);
             return 1;
         }
         const address = ctx.address ?? DEFAULT_ADDRESS;
         const scheme = ctx.tlsCert !== null ? "https" : "http";
         const state = await this.probe(address, ctx.port, ctx.token, ctx.tlsCert !== null);
         if (state === "running") {
-            process.stdout.write(`${this.label}: running on ${scheme}://${urlHost(address)}:${ctx.port}` +
+            await writeStdout(`${this.label}: running on ${scheme}://${urlHost(address)}:${ctx.port}` +
                 (ctx.pid !== null ? ` (pid ${ctx.pid})` : "") + this.running(ctx) + "\n");
             return 0;
         }
         if (state === "unauthorized") {
-            process.stdout.write(`${this.label}: running on ${scheme}://${urlHost(address)}:${ctx.port}, but the configured token is rejected\n`);
+            await writeStdout(`${this.label}: running on ${scheme}://${urlHost(address)}:${ctx.port}, but the configured token is rejected\n`);
             return 1;
         }
         if (state === "foreign") {
-            process.stdout.write(`${this.label}: not running (port ${ctx.port} in use by foreign service)\n`);
+            await writeStdout(`${this.label}: not running (port ${ctx.port} in use by foreign service)\n`);
             return 1;
         }
-        process.stdout.write(`${this.label}: not running (port ${ctx.port} not responding)\n`);
+        await writeStdout(`${this.label}: not running (port ${ctx.port} not responding)\n`);
         return 1;
     }
     /*  stop flow: terminate the server process and wait until it is gone  */

package/dst/ase-mcp.js

@@ -72,7 +72,7 @@ export default class MCPCommand {
             const value = state.getExplicit("basedir");
             return typeof value === "string" && value !== "" ? value : null;
         }
-        catch (_e) {
+        catch {
             /*  best-effort: an unreadable session config just defers the lookup  */
             return null;
         }
@@ -139,7 +139,7 @@ export default class MCPCommand {
             next.onerror = (err) => {
                 this.log.write("error", `mcp: http: ${err.message}`);
             };
-            /*  service closed the connection — try to recover  */
+            /*  service closed the connection -- try to recover  */
             next.onclose = () => {
                 if (client !== next || closedByUs.has(next) || bridgeDone || reconnecting)
                     return;
@@ -183,7 +183,7 @@ export default class MCPCommand {
             if (reconnecting)
                 return;
             reconnecting = true;
-            this.log.write("warning", `mcp: ${reason} — reconnecting`);
+            this.log.write("warning", `mcp: ${reason} -- reconnecting`);
             reconnect(0).catch(() => { });
         };
         /*  bounded buffer for messages arriving while no HTTP client is connected  */
@@ -315,7 +315,7 @@ export default class MCPCommand {
                 await connectClient();
             }
             catch (err) {
-                /*  service vanished between probe and connect — recover instead of crashing  */
+                /*  service vanished between probe and connect -- recover instead of crashing  */
                 triggerReconnect(`initial connect failed: ${this.asError(err).message}`);
             }
         }

package/dst/ase-service-getopt.js

@@ -23,7 +23,7 @@ const tokenizeRanges = (input) => {
                 const quote = ch;
                 i++;
                 while (i < input.length && input[i] !== quote) {
-                    if (input[i] === "\\" && i + 1 < input.length)
+                    if (quote === "\"" && input[i] === "\\" && i + 1 < input.length)
                         i++;
                     i++;
                 }
@@ -50,7 +50,7 @@ const unquote = (s) => {
             const quote = ch;
             j++;
             while (j < s.length && s[j] !== quote) {
-                if (s[j] === "\\" && j + 1 < s.length) {
+                if (quote === "\"" && s[j] === "\\" && j + 1 < s.length) {
                     out += s[j + 1];
                     j += 2;
                 }

package/dst/ase-service-otel.js

@@ -580,7 +580,7 @@ export class UsageTracker {
         const self = userId();
         if (assignee.trim() === "")
             throw new Error("usage: empty assignee (use \"none\" to unassign)");
-        const to = assignee === "me" ? self : assignee.trim();
+        const to = assignee.trim() === "me" ? self : assignee.trim();
         /*  (keep the session out of the adoptions meanwhile, and let an assignment to oneself
             settle the adoption of its active task, as the explicit assignment takes precedence)  */
         this.explicit.add(session);
@@ -591,6 +591,7 @@ export class UsageTracker {
             this.explicit.delete(session);
         }
     }
+    /*  perform the assignment of "assign" (with the session kept out of the adoptions)  */
     async assignSession(id, to, self, session) {
         const warning = await Task.checkAssignee(this.log, to);
         const from = await Task.assign(this.log, id, to === "none" ? null : to);
@@ -952,6 +953,7 @@ export class UsageTracker {
             this.unwatch = null;
         }
     }
+    /*  close resp. implicitly account the open windows of the watched tasks whose assignee changed elsewhere  */
     async check() {
         for (const task of Array.from(this.watched)) {
             const w = this.openWindow(task);
@@ -1212,9 +1214,7 @@ export class UsageTracker {
         (dropping the records of unregistered sessions), with the session registry
         re-read from the telemetry state file only once the file changed  */
     route(records) {
-        const bySession = new Map();
-        for (const r of records)
-            bySession.set(r.session, [...(bySession.get(r.session) ?? []), r]);
+        const bySession = Map.groupBy(records, (r) => r.session);
         let registry;
         try {
             const file = UsageTracker.stateFile();

package/dst/ase-service-skills.js

@@ -187,7 +187,8 @@ export class Skills {
             if (m === null)
                 return "N.A.";
             const base = parseFloat(m[1].replace(/,/g, ""));
-            const mult = m[2] === "K" ? 1_000 : m[2] === "M" ? 1_000_000 : m[2] === "B" ? 1_000_000_000 : 1;
+            const unit = m[2].toUpperCase();
+            const mult = unit === "K" ? 1_000 : unit === "M" ? 1_000_000 : unit === "B" ? 1_000_000_000 : 1;
             const n = Math.round(base * mult);
             return Number.isFinite(n) ? n : "N.A.";
         }
@@ -246,20 +247,9 @@ export class Skills {
         const now = Date.now();
         const msPerDay = 1000 * 60 * 60 * 24;
         const halfLife = 365 / 2;
-        /*  lifespan requires both timestamps; recentness requires the
-            updated timestamp -- any unavailable date-derived factor is
-            given a neutral default so the entry can still be ranked by the
-            remaining metrics, instead of collapsing the product to zero.
-            For `lifespan` (an unbounded duration) the multiplicative-neutral
-            `1` is also the low floor, so a missing value cannot unfairly
-            inflate the rank. For `recentness`, however, the value is an
-            exp-decay factor bounded in `(0,1]` where `1` is the *ceiling*
-            (a just-now update), not a floor -- defaulting a missing update
-            date to `1` would hand packages with absent metadata the highest
-            possible recentness and let them outrank genuinely fresh ones.
-            We therefore default a missing `recentness` to the decay value at
-            one half-life (`0.5`), a conservative midpoint that keeps the
-            entry rankable without rewarding the missing date.  */
+        /*  an unavailable date-derived factor gets a neutral default: a missing lifespan
+            its floor "1", a missing recentness (whose ceiling is "1") the decay value at
+            one half-life ("0.5"), so a missing date is never rewarded  */
         const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(1, uMs - cMs) : 1;
         const recentness = !Number.isNaN(uMs) ? 0.5 ** (Math.max(0, (now - uMs) / msPerDay) / halfLife) : 0.5;
         let rank = d * s * lifespan * recentness;