@rse/ase 2.0.2 → 2.0.4

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

@@ -14,8 +14,7 @@ import { Config } from "./ase-config-core.js";
 import { parseScope } from "./ase-config-scope.js";
 import { isLogLevel } from "./ase-lib-log.js";
 import { writeStdout } from "./ase-lib-stdio.js";
-import { Service } from "./ase-service.js";
-import { DaemonCommand } from "./ase-lib-daemon-cli.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";
@@ -45,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  */
         }
     }
@@ -271,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" ?
@@ -352,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 === "")

package/dst/ase-lib-version.js

@@ -13,18 +13,27 @@ export default class Version {
         return pkg.version;
     }
     /*  return latest ASE version known from the NPM registry
-        (cached background check, falling back to the current version)  */
-    static async latest() {
+        (cached background check or, if requested, immediate direct check,
+        both falling back to the current version)  */
+    static async latest(direct = false) {
         const notifier = updateNotifier({
             pkg,
             updateCheckInterval: 1000 * 60 * 60
         });
-        /*  re-persist the cached update information, as update-notifier consumes it on read,
+        /*  optionally query the NPM registry directly, where only
+            a successful query supersedes the cached update information  */
+        let update = notifier.update;
+        if (direct) {
+            const info = await Promise.resolve(notifier.fetchInfo()).catch(() => undefined);
+            if (info !== undefined)
+                update = info;
+        }
+        /*  re-persist the update information, as update-notifier consumes it on read,
             but only while it still denotes a newer version (it is never cleared otherwise)  */
-        const latest = notifier.update?.latest;
+        const latest = update?.latest;
         if (latest === undefined || !semver.valid(latest) || !semver.gt(latest, Version.current()))
             return Version.current();
-        notifier.config?.set("update", notifier.update);
+        notifier.config?.set("update", update);
         return latest;
     }
 }

package/dst/ase-man-catalog.js

@@ -0,0 +1,229 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { fuzzyMin, levenshtein, diceCoefficient } from "./ase-task-board-filter.js";
+/*  the grouping and ordering of the skills: a copy of the groups shown by the
+    catalog of the website ("skillPrefixGroups" of "pages/src/data/skills.ts",
+    in the column order of "Section-Usage.astro"), so keep both in sync, where
+    any skill not listed here is caught by a trailing "OTHER" group  */
+const skillGroups = [
+    ["HELP", ["ase-help-skill", "ase-help-intent"]],
+    ["META: CONFIG", ["ase-meta-config", "ase-meta-compat"]],
+    ["META: EXPLAIN", ["ase-meta-why", "ase-meta-eli5"]],
+    ["META: JUDGE", ["ase-meta-evaluate", "ase-meta-diaboli", "ase-meta-steelman"]],
+    ["META: RESEARCH", ["ase-meta-brainstorm", "ase-meta-search", "ase-meta-quorum",
+            "ase-meta-proximity", "ase-meta-chat", "ase-meta-quotes"]],
+    ["META: GENERATE", ["ase-meta-mint", "ase-meta-workflow"]],
+    ["ARCH", ["ase-arch-analyze", "ase-arch-discover"]],
+    ["DOCS", ["ase-docs-shorten", "ase-docs-refine", "ase-docs-proofread", "ase-docs-distill"]],
+    ["SPEC", ["ase-spec-lint", "ase-spec-edit", "ase-spec-activate"]],
+    ["CODE", ["ase-code-edit", "ase-code-analyze", "ase-code-insight", "ase-code-explain", "ase-code-lint"]],
+    ["REPO", ["ase-repo-review", "ase-repo-diff", "ase-repo-changelog", "ase-repo-commit",
+            "ase-repo-dissect", "ase-repo-merge", "ase-repo-resolve"]],
+    ["SYNC", ["ase-sync-reconcile", "ase-sync-import", "ase-sync-export"]],
+    ["TASK: MANAGE", ["ase-task-list", "ase-task-rename", "ase-task-delete"]],
+    ["TASK: HANDLE", ["ase-task-id", "ase-task-status", "ase-task-assign"]],
+    ["TASK: EDIT", ["ase-task-edit", "ase-task-view", "ase-task-grill", "ase-task-research",
+            "ase-task-estimate", "ase-task-reboot", "ase-task-condense", "ase-task-dissect"]],
+    ["TASK: EXECUTE", ["ase-task-implement", "ase-task-integrate"]]
+];
+/*  the order of the command groups: a copy of the column order of "manColumns"
+    of "pages/src/data/manpages.ts", so keep both in sync, where any group not
+    listed here (like the one of a newly added top-level command) is appended  */
+const commandGroups = ["Top-Level", "setup", "config", "service", "task", "spec", "util", "artifact", "agent", "hook"];
+/*  read the Markdown sources of the entries of a directory, by the page
+    names and the relative source paths derived from the entry names  */
+const readSources = (dir, pick) => {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (err) {
+        throw new Error(`man: no manual pages found in "${dir}" (tool not completely built?)`, { cause: err });
+    }
+    const sources = new Map();
+    for (const entry of entries) {
+        const picked = pick(entry);
+        if (picked !== null && fs.existsSync(path.join(dir, picked[1])))
+            sources.set(picked[0], fs.readFileSync(path.join(dir, picked[1]), "utf8"));
+    }
+    return sources;
+};
+/*  create a manual page  */
+const makePage = (id, kind, label, title, md) => {
+    const text = md.toLowerCase();
+    return { id, kind, label, title, md, text, words: new Set(text.split(/[^a-z0-9]+/).filter((w) => w !== "")) };
+};
+/*  load the skill pages from the "help.md" files of the bundled plugin (see
+    the "build-plugin" build step), grouped like the catalog of the website  */
+const loadSkills = () => {
+    const pkgdir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const dir = path.join(pkgdir, "plugin", "skills");
+    const sources = readSources(dir, (entry) => /^ase-[a-z0-9-]+$/.test(entry) ? [entry, path.join(entry, "help.md")] : null);
+    const page = (name) => {
+        const md = sources.get(name);
+        const m = /^#+\s+NAME\s*\n+\s*`?[\w-]+`?\s+-+\s+(.+)$/m.exec(md);
+        return makePage(name, "skill", name, m !== null ? m[1].trim() : name, md);
+    };
+    const listed = new Set(skillGroups.flatMap(([, names]) => names));
+    const other = [...sources.keys()].filter((name) => !listed.has(name)).sort();
+    return [...skillGroups, ["OTHER", other]]
+        .map(([label, names]) => ({ label, pages: names.filter((name) => sources.has(name)).map(page) }))
+        .filter((group) => group.pages.length > 0);
+};
+/*  load the command pages from the Markdown sources of the manual pages
+    (see the "build-man" build step), arranged into the command tree and
+    grouped like the catalog of the website ("pages/src/data/manpages.ts")  */
+const loadCommands = () => {
+    const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), "man");
+    const sources = readSources(dir, (entry) => /^ase(?:-[a-z0-9-]+)?\.md$/.test(entry) ? [entry.slice(0, -3), entry] : null);
+    const names = [...sources.keys()].sort();
+    /*  the parent of a page is the longest other page name it extends by a "-<suffix>"  */
+    const parentOf = (name) => names.filter((other) => name.startsWith(other + "-"))
+        .sort((a, b) => b.length - a.length)[0] ?? "";
+    /*  the children of a page, ordered by their first "`<name>`(1)" reference
+        within the COMMANDS section of the page (or the entire page), else alphabetically  */
+    const childrenOf = (parent) => {
+        const md = sources.get(parent);
+        const m = /^## COMMANDS\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(md);
+        const section = m !== null ? m[1] : md;
+        const pos = (name) => {
+            const idx = section.indexOf("`" + name + "`(1)");
+            return idx >= 0 ? idx : Infinity;
+        };
+        return names.filter((name) => parentOf(name) === parent)
+            .sort((a, b) => (pos(a) - pos(b)) || a.localeCompare(b));
+    };
+    /*  flatten the command tree depth-first  */
+    const tree = [];
+    const walk = (name, label, depth) => {
+        const md = sources.get(name);
+        const m = /^#\s+\S+\(1\)\s+--\s+(.+)$/m.exec(md);
+        tree.push({ page: makePage(`${name}.1`, "command", label, m !== null ? m[1].trim() : name, md), depth });
+        for (const child of childrenOf(name))
+            walk(child, label + " " + child.slice(name.length + 1), depth + 1);
+    };
+    for (const root of names.filter((name) => parentOf(name) === ""))
+        walk(root, root.replace(/-/g, " "), 0);
+    /*  group the command tree: "ase" itself and the top-level commands without
+        sub-commands form the "Top-Level" group, and every other top-level
+        command forms an own group with all of its deeper commands  */
+    const groups = [{ label: "Top-Level", pages: [] }];
+    for (const { page, depth } of tree) {
+        if (depth === 0)
+            groups[0].pages.push(page);
+        else if (depth === 1) {
+            if (tree.some((other) => other.depth > 1 && other.page.label.startsWith(page.label + " ")))
+                groups.push({ label: page.label.slice(page.label.lastIndexOf(" ") + 1), pages: [page] });
+            else
+                groups[0].pages.push(page);
+        }
+        else
+            groups[groups.length - 1].pages.push(page);
+    }
+    const rank = (group) => {
+        const idx = commandGroups.indexOf(group.label);
+        return idx >= 0 ? idx : commandGroups.length;
+    };
+    return groups
+        .filter((group) => group.pages.length > 0)
+        .sort((a, b) => rank(a) - rank(b))
+        .map((group) => ({ ...group, label: group.label.toUpperCase() }));
+};
+/*  load the catalog of all manual pages  */
+export const loadCatalog = () => {
+    const skills = loadSkills();
+    const commands = loadCommands();
+    const pages = new Map([...skills, ...commands].flatMap((group) => group.pages).map((page) => [page.id, page]));
+    const vocab = new Set([...pages.values()].flatMap((page) => [...page.words]));
+    return { skills, commands, pages, vocab };
+};
+/*  find the page fitting exactly onto the words of a page name or command path,
+    which are joined with dashes, where the "ase" prefix is optional, the name is
+    case-insensitive, and of a skill and a command of the same name, a page name
+    (e.g. "task-edit") prefers the skill, while a command path (e.g. "task edit")
+    prefers the command  */
+export const findPage = (catalog, words) => {
+    const parts = words.join(" ").trim().toLowerCase().split(/\s+/);
+    const name = parts.join("-");
+    const full = name === "ase" || name.startsWith("ase-") ? name : `ase-${name}`;
+    const skill = catalog.pages.get(full);
+    const command = catalog.pages.get(`${full}.1`);
+    return parts.length === 1 && name.includes("-") ? skill ?? command : command ?? skill;
+};
+/*  escape a string for its literal use within a regular expression  */
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/*  the regular expression of the matches of a search in a page: the
+    keywords as plain substrings, plus the fuzzy variants of the page as
+    whole words, with the longest alternative first, so a variant is never
+    cut short by a keyword nested inside it  */
+const matchRE = (keywords, variants) => {
+    const alts = keywords.map((k) => ({ len: k.length, src: escape(k) }))
+        .concat(variants.map((w) => ({ len: w.length, src: "(?<![a-z0-9])" + escape(w) + "(?![a-z0-9])" })));
+    alts.sort((a, b) => b.len - a.len);
+    return new RegExp(alts.map((a) => a.src).join("|"), "gi");
+};
+/*  search all pages for a query (as the website does): all whitespace-separated
+    keywords have to occur in a page (AND logic), in up to two passes, the
+    keywords as literal substrings first and, only if this matches no page at
+    all, as fuzzy variants of their words, as the edit-distance neighborhood of
+    a keyword would otherwise dilute a correctly spelled query; the result
+    maps the ids of the matching pages onto the regular expressions of their
+    matches, or is null for a query without any keywords  */
+export const searchPages = (catalog, query) => {
+    const keywords = query.toLowerCase().split(/\s+/).filter((word) => word !== "");
+    if (keywords.length === 0)
+        return null;
+    const pages = [...catalog.pages.values()];
+    const hits = new Map();
+    for (const page of pages)
+        if (keywords.every((k) => page.text.includes(k)))
+            hits.set(page.id, matchRE(keywords, []));
+    if (hits.size > 0)
+        return hits;
+    /*  the fuzzy-equivalent vocabulary words of a keyword, cached per keyword  */
+    const fuzzy = new Map();
+    const fuzzyWords = (word) => {
+        let result = fuzzy.get(word);
+        if (result === undefined) {
+            result = word.length < fuzzyMin ? [] : [...catalog.vocab].filter((given) => Math.abs(word.length - given.length) <= 1
+                && (diceCoefficient(word, given) >= 0.50 || levenshtein(word, given) <= 2));
+            fuzzy.set(word, result);
+        }
+        return result;
+    };
+    /*  the regular expression of the fuzzy variants of a compound keyword (like
+        "ase-task-edit"), with each of its words literally or fuzzily replaced
+        and its separators kept, cached per keyword (null for a single word)  */
+    const compound = new Map();
+    const compoundRE = (keyword) => {
+        let result = compound.get(keyword);
+        if (result === undefined) {
+            const parts = keyword.split(/([^a-z0-9]+)/);
+            result = parts.length < 2 ? null : new RegExp("(?<![a-z0-9])" + parts.map((part, i) => i % 2 === 1 ? escape(part) : part === "" ? "" :
+                "(?:" + [part, ...fuzzyWords(part)].map(escape).join("|") + ")").join("") + "(?![a-z0-9])", "g");
+            compound.set(keyword, result);
+        }
+        return result;
+    };
+    for (const page of pages) {
+        const variants = [];
+        const hit = keywords.every((k) => {
+            if (page.text.includes(k))
+                return true;
+            const re = compoundRE(k);
+            const near = re !== null ? [...new Set([...page.text.matchAll(re)].map((m) => m[0]))] :
+                fuzzyWords(k).filter((w) => page.words.has(w));
+            variants.push(...near);
+            return near.length > 0;
+        });
+        if (hit)
+            hits.set(page.id, matchRE(keywords, variants));
+    }
+    return hits;
+};