@rse/ase 1.0.7 → 2.0.0

package/dst/ase-service.js

@@ -13,24 +13,30 @@ import { ofetch } from "ofetch";
 import { isMap } from "yaml";
 import prettyMs from "pretty-ms";
 import * as v from "valibot";
+import { Tail } from "tail";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { Config, configSchema, ConfigMCP } from "./ase-config.js";
-import { isLogLevel } from "./ase-log.js";
-import { CompatMCP } from "./ase-compat.js";
-import { DiagramMCP } from "./ase-diagram.js";
-import { TaskMCP } from "./ase-task.js";
-import { MarkdownMCP } from "./ase-markdown.js";
+import { ConfigMCP } from "./ase-config.js";
+import { Config } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
+import { ensureAseGitignore } from "./ase-config-scope.js";
+import { isLogLevel } from "./ase-lib-log.js";
+import { CompatMCP } from "./ase-util-compat.js";
+import { DiagramMCP } from "./ase-util-diagram.js";
+import { Task, TaskMCP } from "./ase-task.js";
+import { MarkdownMCP } from "./ase-service-markdown.js";
 import { ArtifactMCP } from "./ase-artifact.js";
 import { SpecMCP } from "./ase-spec.js";
-import { KVMCP } from "./ase-kv.js";
-import { TimestampMCP } from "./ase-timestamp.js";
-import { SleepMCP } from "./ase-sleep.js";
-import { GetoptMCP } from "./ase-getopt.js";
-import { SkillsMCP } from "./ase-skills.js";
-import { WorktreeMCP } from "./ase-worktree.js";
-import { MintMCP } from "./ase-mint.js";
-import { MetricMCP } from "./ase-metric.js";
+import { KVMCP } from "./ase-service-kv.js";
+import { StateMCP } from "./ase-service-state.js";
+import { TimestampMCP } from "./ase-service-timestamp.js";
+import { SleepMCP } from "./ase-service-sleep.js";
+import { GetoptMCP } from "./ase-service-getopt.js";
+import { SkillsMCP } from "./ase-service-skills.js";
+import { WorktreeMCP } from "./ase-util-worktree.js";
+import { MintMCP } from "./ase-util-mint.js";
+import { MetricMCP } from "./ase-util-metric.js";
+import { UsageTracker } from "./ase-service-otel.js";
 import pkg from "../package.json" with { type: "json" };
 /*  shared service host  */
 export const SERVICE_HOST = "127.0.0.1";
@@ -88,7 +94,7 @@ export const loadServiceContext = (log) => {
     const svc = new Config("service", serviceSchema, log);
     svc.read();
     /*  determine project id  */
-    const projectId = cfg.get("project.id") ?? path.basename(process.cwd());
+    const projectId = cfg.get("project.id") || Task.projectIdOf(Task.projectRoot());
     /*  determine service port  */
     const port = svc.get("port") ?? null;
     /*  determine path to ".ase" directory  */
@@ -122,6 +128,7 @@ export class Service {
     }
     /*  persist an allocated port into ".ase/service.yaml"  */
     static persistPort(svc, port) {
+        ensureAseGitignore(path.dirname(svc.filename));
         svc.lock(() => {
             svc.read();
             svc.set("port", port);
@@ -159,6 +166,7 @@ export class Service {
     /*  spawn the current executable detached as a background service  */
     static spawnDetached(aseDir, port, logLevel) {
         fs.mkdirSync(aseDir, { recursive: true });
+        ensureAseGitignore(aseDir);
         const logFile = path.join(aseDir, "service.log");
         /*  trim the log before handing it to the service, as the detached
             service inherits the file descriptor for its entire lifetime and
@@ -208,6 +216,34 @@ export class Service {
                 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 ?
+            Service.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;
+    }
 }
 /*  MCP registration entry point for service-identity tools  */
 export class ServiceMCP {
@@ -243,8 +279,56 @@ export default class ServiceCommand {
     loadContext() {
         return loadServiceContext(this.log);
     }
-    /*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
-    async runService(ctx) {
+    /*  build a fresh MCP server instance with all registered tools
+        (also used by the "ase mcp" bridge for answering the MCP handshake
+        and tool listing in-process before the service is started)  */
+    static buildMcpServer(log, ctx, startTime, usage) {
+        const mcp = new McpServer({ name: "ase", version: pkg.version });
+        new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
+        new CompatMCP().register(mcp);
+        new DiagramMCP().register(mcp);
+        new TaskMCP(log, usage).register(mcp);
+        new MarkdownMCP().register(mcp);
+        new ArtifactMCP(log).register(mcp);
+        new SpecMCP(log).register(mcp);
+        new KVMCP().register(mcp);
+        new TimestampMCP().register(mcp);
+        new SleepMCP().register(mcp);
+        new GetoptMCP().register(mcp);
+        new SkillsMCP().register(mcp);
+        new WorktreeMCP().register(mcp);
+        new MintMCP().register(mcp);
+        new MetricMCP().register(mcp);
+        new ConfigMCP(log).register(mcp);
+        new StateMCP(log).register(mcp);
+        return mcp;
+    }
+    /*  summarize the method, tool name, and capped tool arguments of an MCP request body  */
+    static mcpBodyInfo(body) {
+        const b = body;
+        const bParams = b?.params;
+        const bMethod = typeof b?.method === "string" ? b.method : null;
+        const bName = typeof bParams?.name === "string" ? bParams.name : null;
+        const bArgs = bParams?.arguments !== undefined ? bParams.arguments : null;
+        let info = "";
+        if (bMethod !== null) {
+            info = ` [${bMethod}]`;
+            if (bName !== null) {
+                info += ` ${bName}`;
+                if (bArgs !== null) {
+                    /*  cap the arguments, as payload-carrying tool calls
+                        (task plans, key/value batches, etc) would
+                        otherwise dominate the entire log file  */
+                    const args = JSON.stringify(bArgs);
+                    info += ` ${args.length > LOG_ARGS_MAX ? `${args.slice(0, LOG_ARGS_MAX)}…` : args}`;
+                }
+            }
+        }
+        return { method: bMethod, info };
+    }
+    /*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens
+        (or, in the foreground, until "/stop" command is received or a termination signal arrives)  */
+    async runService(ctx, foreground = false) {
         /*  establish HAPI HTTP/REST service  */
         const server = Hapi.server({ host: HOST, port: ctx.port });
         /*  track start time and last activity  */
@@ -252,9 +336,14 @@ export default class ServiceCommand {
         let lastActivity = Date.now();
         let inFlight = 0;
         let stopping = false;
-        server.ext("onRequest", (_request, h) => {
+        /*  accept only loopback "Host" headers, to defeat DNS rebinding attacks from browser pages  */
+        const allowedHosts = new Set([`${HOST}:${ctx.port}`, `localhost:${ctx.port}`]);
+        server.ext("onRequest", (request, h) => {
             inFlight++;
             lastActivity = Date.now();
+            const host = (request.headers.host ?? "").toLowerCase();
+            if (!allowedHosts.has(host))
+                return h.response({ error: "invalid Host header" }).code(421).takeover();
             return h.continue;
         });
         server.ext("onPreResponse", (_request, h) => {
@@ -262,27 +351,10 @@ export default class ServiceCommand {
             lastActivity = Date.now();
             return h.continue;
         });
-        /*  build a fresh MCP server instance with all registered tools  */
-        const buildMcpServer = () => {
-            const mcp = new McpServer({ name: "ase", version: pkg.version });
-            new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
-            new CompatMCP().register(mcp);
-            new DiagramMCP().register(mcp);
-            new TaskMCP(this.log).register(mcp);
-            new MarkdownMCP().register(mcp);
-            new ArtifactMCP(this.log).register(mcp);
-            new SpecMCP(this.log).register(mcp);
-            new KVMCP().register(mcp);
-            new TimestampMCP().register(mcp);
-            new SleepMCP().register(mcp);
-            new GetoptMCP().register(mcp);
-            new SkillsMCP().register(mcp);
-            new WorktreeMCP().register(mcp);
-            new MintMCP().register(mcp);
-            new MetricMCP().register(mcp);
-            new ConfigMCP(this.log).register(mcp);
-            return mcp;
-        };
+        /*  establish the usage tracker of the AI usage accounting (and the OTLP ingress)  */
+        const usage = new UsageTracker(this.log, Task.projectRoot(), ctx.projectId, ctx.aseDir, () => {
+            lastActivity = Date.now();
+        });
         /*  listen to HTTP/REST endpoints  */
         server.route({
             method: "OPTIONS",
@@ -292,9 +364,14 @@ export default class ServiceCommand {
             }
         });
         server.route({
-            method: "GET",
+            method: "POST",
             path: "/stop",
-            handler: (_request, h) => {
+            handler: (request, h) => {
+                /*  require a JSON content type, as browsers cannot send it cross-origin
+                    without a CORS preflight (which this service never grants)  */
+                const ct = (request.headers["content-type"] ?? "").toLowerCase();
+                if (!ct.startsWith("application/json"))
+                    return h.response({ error: "unsupported media type" }).code(415);
                 this.log.write("info", "service: stop requested");
                 setImmediate(async () => {
                     try {
@@ -304,38 +381,21 @@ export default class ServiceCommand {
                         const e = err;
                         this.log.write("error", `service: stop failed: ${e.message}`);
                     }
+                    await usage.stop();
                     process.exit(0);
                 });
                 return h.response({ ok: true }).code(200);
             }
         });
         const mcpHandler = async (request, h, body) => {
-            const b = body;
-            const bParams = b?.params;
-            const bMethod = typeof b?.method === "string" ? b.method : null;
-            const bName = typeof bParams?.name === "string" ? bParams.name : null;
-            const bArgs = bParams?.arguments !== undefined ? bParams.arguments : null;
-            let bodyInfo = "";
-            if (bMethod !== null) {
-                bodyInfo = ` [${bMethod}]`;
-                if (bName !== null) {
-                    bodyInfo += ` ${bName}`;
-                    if (bArgs !== null) {
-                        /*  cap the arguments, as payload-carrying tool calls
-                            (task plans, key/value batches, etc) would
-                            otherwise dominate the entire log file  */
-                        const args = JSON.stringify(bArgs);
-                        bodyInfo += ` ${args.length > LOG_ARGS_MAX ? `${args.slice(0, LOG_ARGS_MAX)}…` : args}`;
-                    }
-                }
-            }
+            const { method: bMethod, info: bodyInfo } = ServiceCommand.mcpBodyInfo(body);
             /*  log tool calls regularly, but all remaining MCP traffic
                 (session handshakes, notifications, SSE stream opens) at
                 debug level only, as it carries no diagnostic value  */
             const level = bMethod === "tools/call" ? "info" : "debug";
             this.log.write(level, `mcp: ${request.method.toUpperCase()} ${request.path}${bodyInfo}`);
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-            const mcp = buildMcpServer();
+            const mcp = ServiceCommand.buildMcpServer(this.log, ctx, startTime, usage);
             request.raw.res.on("close", () => {
                 /*  "h.abandon" (see below) bypasses "onPreResponse",
                     so undo the "onRequest" accounting here instead  */
@@ -390,11 +450,77 @@ export default class ServiceCommand {
                 return h.response({ error: "unknown command", command: cmd }).code(400);
             }
         });
+        /*  listen to the endpoints of the AI usage accounting: the usage records forwarded
+            by the OTLP ingress, the session end, the task assignment on behalf of a session,
+            and the task rename  */
+        server.route({
+            method: "POST",
+            path: "/usage/records",
+            options: { payload: { parse: true, allow: "application/json", maxBytes: 32 * 1024 * 1024 } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (!Array.isArray(payload?.records))
+                    return h.response({ error: "missing or invalid 'records' field" }).code(400);
+                usage.ingest(payload.records);
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/detach",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.session !== "string")
+                    return h.response({ error: "missing or invalid 'session' field" }).code(400);
+                usage.detach(payload.session);
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/rename",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.old !== "string" || typeof payload.new !== "string")
+                    return h.response({ error: "missing or invalid 'old' or 'new' field" }).code(400);
+                try {
+                    usage.rename(payload.old, payload.new);
+                }
+                catch (err) {
+                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
+                }
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/assign",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: async (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.id !== "string" || typeof payload.assignee !== "string" || typeof payload.session !== "string")
+                    return h.response({ error: "missing or invalid 'id', 'assignee', or 'session' field" }).code(400);
+                try {
+                    return h.response(await usage.assign(payload.id, payload.assignee, payload.session)).code(200);
+                }
+                catch (err) {
+                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
+                }
+            }
+        });
+        /*  serve the web board of the project (imported dynamically to keep it out of all
+            other CLI commands; its rendering dependencies marked, MRCS, and ELK load on
+            first request only, its board core dependencies at service startup)  */
+        const { registerBoardRoutes } = await import("./ase-task-board-web-server.js");
+        registerBoardRoutes(server, this.log);
         /*  start service  */
         try {
             await server.start();
             Service.persistPort(ctx.svc, ctx.port);
             this.log.write("info", `service: listening on port ${ctx.port}`);
+            usage.start();
         }
         catch (err) {
             const e = err;
@@ -410,31 +536,60 @@ export default class ServiceCommand {
             this.log.write("error", `service: ${e.message}`);
             process.exit(1);
         }
+        /*  stop service in the foreground on termination signal  */
+        if (foreground) {
+            const shutdown = async (signal) => {
+                if (stopping)
+                    return;
+                stopping = true;
+                this.log.write("info", `service: received ${signal}, stopping`);
+                try {
+                    await server.stop({ timeout: 1000 });
+                }
+                catch (err) {
+                    const e = err;
+                    this.log.write("error", `service: stop failed: ${e.message}`);
+                }
+                await usage.stop();
+                Service.clearPort(ctx.svc);
+                process.exit(0);
+            };
+            process.on("SIGTERM", () => shutdown("SIGTERM"));
+            process.on("SIGINT", () => shutdown("SIGINT"));
+            process.on("SIGHUP", () => shutdown("SIGHUP"));
+            process.on("SIGQUIT", () => shutdown("SIGQUIT"));
+            return;
+        }
         /*  stop service after idle timeout  */
         setInterval(async () => {
             if (stopping)
                 return;
             if (inFlight > 0)
                 return;
+            /*  never idle out while holding usage windows, as their sessions keep on reporting  */
+            if (usage.active())
+                return;
             if (Date.now() - lastActivity > IDLE_MS) {
                 stopping = true;
                 this.log.write("info", "service: idle timeout reached, stopping");
                 try {
                     await server.stop({ timeout: 1000 });
+                    await usage.stop();
                     Service.clearPort(ctx.svc);
                     process.exit(0);
                 }
                 catch (err) {
                     const e = err;
                     this.log.write("error", `service: stop failed: ${e.message}`);
+                    await usage.stop();
                     Service.clearPort(ctx.svc);
                     process.exit(1);
                 }
             }
         }, TICK_MS).unref();
     }
-    /*  start flow: ensure port, probe, optionally detach  */
-    async doStart() {
+    /*  start flow: ensure port, probe, optionally detach (or run in the foreground)  */
+    async doStart(opts = {}) {
         const ctx = this.loadContext();
         let port = ctx.port;
         if (process.env[SERVE_ENV] === "1") {
@@ -451,10 +606,18 @@ export default class ServiceCommand {
         if (port !== null) {
             const match = await probe(port, ctx.projectId).catch(() => null);
             if (match === true) {
+                if (opts.foreground)
+                    throw new Error(`service: already running on port ${port} (stop it first with "ase service stop")`);
                 this.log.write("info", `service: already running on port ${port}`);
                 return 0;
             }
         }
+        /*  run the service in the foreground, logging to the terminal and without idle timeout  */
+        if (opts.foreground) {
+            port = await Service.allocatePort();
+            await this.runService({ ...ctx, port }, true);
+            return await new Promise(() => { });
+        }
         /*  bounded retry across the bind/start TOCTOU window: on each attempt
             re-allocate, re-spawn; early-break on foreign listener  */
         let lastErr = new Error("service failed to start within timeout");
@@ -524,12 +687,12 @@ export default class ServiceCommand {
         }
         throw lastErr;
     }
-    /*  build the "POST /command" request options for a command token  */
-    commandRequest(cmd, timeoutMs) {
+    /*  build the JSON "POST" request options for a service endpoint  */
+    postRequest(body, timeoutMs) {
         return {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: { command: cmd },
+            body,
             signal: AbortSignal.timeout(timeoutMs),
             ignoreResponseError: true
         };
@@ -543,7 +706,7 @@ export default class ServiceCommand {
         }
         const match = await probe(ctx.port, ctx.projectId).catch(() => null);
         if (match === true) {
-            const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, this.commandRequest("status", 2000));
+            const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, this.postRequest({ command: "status" }, 2000));
             const d = r._data;
             const uptimeMs = typeof d?.uptimeMs === "number" ? d.uptimeMs : 0;
             const uptime = prettyMs(uptimeMs, { verbose: true });
@@ -569,13 +732,18 @@ export default class ServiceCommand {
             if (await probe(ctx.port, ctx.projectId).catch(() => null) !== true)
                 throw new Error(`service not responding on port ${ctx.port} after auto-start`);
         }
-        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, { ...this.commandRequest(cmd, 5000), responseType: "text" });
+        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, { ...this.postRequest({ command: cmd }, 5000), responseType: "text" });
         const body = typeof r._data === "string" ? r._data : JSON.stringify(r._data);
         process.stdout.write(body);
         if (!body.endsWith("\n"))
             process.stdout.write("\n");
         return r.status >= 200 && r.status < 300 ? 0 : 1;
     }
+    /*  log flow: show the (tail of the) log file and optionally follow it  */
+    async doLog(opts) {
+        const ctx = this.loadContext();
+        return Service.showLog(path.join(ctx.aseDir, "service.log"), opts);
+    }
     /*  stop flow: no-op if no port configured or connection refused  */
     async doStop() {
         const ctx = this.loadContext();
@@ -593,11 +761,7 @@ export default class ServiceCommand {
             Service.clearPort(ctx.svc);
             return 0;
         }
-        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/stop`, {
-            method: "GET",
-            signal: AbortSignal.timeout(5000),
-            ignoreResponseError: true
-        });
+        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/stop`, this.postRequest({}, 5000));
         const ok = r.status >= 200 && r.status < 300;
         Service.clearPort(ctx.svc);
         return ok ? 0 : 1;
@@ -615,9 +779,11 @@ export default class ServiceCommand {
         /*  register CLI sub-command "ase service start"  */
         service
             .command("start")
-            .description("Start the background service")
-            .action(async () => {
-            process.exit(await this.doStart());
+            .description("Start the background service (or run it in the foreground)")
+            .option("-f, --foreground", "run the service in the foreground, logging to the terminal, " +
+            "until it is interrupted or stopped (without idle timeout)")
+            .action(async (opts) => {
+            process.exit(await this.doStart(opts));
         });
         /*  register CLI sub-command "ase service status"  */
         service
@@ -634,6 +800,15 @@ export default class ServiceCommand {
             .action(async (cmd) => {
             process.exit(await this.doSend(cmd));
         });
+        /*  register CLI sub-command "ase service log"  */
+        service
+            .command("log")
+            .description("Show the log of the background service")
+            .option("-f, --follow", "keep following the log for newly appended lines")
+            .option("-n, --lines <n>", "show the last <n> lines only (default: all, or 10 with --follow)")
+            .action(async (opts) => {
+            process.exit(await this.doLog(opts));
+        });
         /*  register CLI sub-command "ase service stop"  */
         service
             .command("stop")

package/dst/ase-setup-common.js

@@ -0,0 +1,141 @@
+/*
+**  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 fs from "node:fs/promises";
+import path from "node:path";
+import { execa } from "execa";
+import which from "which";
+export const toolSpecs = {
+    "claude": { cli: "claude", label: "Anthropic Claude Code CLI", pInstall: "install", pRemove: "uninstall", pUpdate: "update" },
+    "copilot": { cli: "copilot", label: "GitHub Copilot CLI", pInstall: "install", pRemove: "uninstall", pUpdate: "update" },
+    "codex": { cli: "codex", label: "OpenAI Codex CLI", pInstall: "add", pRemove: "remove", pUpdate: "upgrade" }
+};
+/*  parse and validate the --tool option  */
+export const parseTool = (value) => {
+    if (value !== "claude" && value !== "copilot" && value !== "codex")
+        throw new Error(`invalid --tool value: "${value}" (expected "claude", "copilot", or "codex")`);
+    return value;
+};
+/*  parse and validate the --scope option  */
+export const parseScope = (value) => {
+    if (value !== "user" && value !== "project" && value !== "local")
+        throw new Error(`invalid --scope value: "${value}" (expected "user", "project", or "local")`);
+    return value;
+};
+/*  reject a non-default --scope for tools which have no scope concept
+    at all (only Anthropic Claude Code CLI supports plugin/MCP scopes)  */
+export const requireClaudeScope = (tool, scope) => {
+    if (tool !== "claude" && scope !== "user")
+        throw new Error("--scope is only supported for --tool claude");
+};
+/*  sub-process runner of "ase setup"  */
+export class SetupRunner {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  ensure a tool is available  */
+    async ensureTool(tool) {
+        return which(tool).catch(() => {
+            throw new Error(`mandatory tool "${tool}" not found in $PATH`);
+        });
+    }
+    /*  determine whether a global "npm" operation requires "sudo" by
+        checking whether the npm global install root is writable by the
+        current user; on Windows or when already running as root, no
+        elevation is needed  */
+    async npmGlobalNeedsSudo() {
+        /*  Windows has no "sudo" concept here  */
+        if (process.platform === "win32")
+            return false;
+        /*  already running as root  */
+        const getuid = process.getuid;
+        if (typeof getuid === "function" && getuid.call(process) === 0)
+            return false;
+        /*  determine the npm global prefix and probe writability of the
+            directories that "npm -g" actually mutates  */
+        let prefix;
+        try {
+            const result = await execa("npm", ["prefix", "-g"], { stdio: "pipe" });
+            prefix = result.stdout.trim();
+        }
+        catch {
+            /*  if we cannot determine the prefix, fall back to "no sudo"  */
+            return false;
+        }
+        if (prefix === "")
+            return false;
+        const candidates = [
+            prefix,
+            path.join(prefix, "bin"),
+            path.join(prefix, "lib", "node_modules")
+        ];
+        const accessible = (dir, mode) => fs.access(dir, mode).then(() => true, () => false);
+        for (const dir of candidates) {
+            /*  a writable directory needs no elevation at all  */
+            if (await accessible(dir, fs.constants.W_OK))
+                continue;
+            /*  the directory exists, but is not writable: require sudo  */
+            if (await accessible(dir, fs.constants.F_OK))
+                return true;
+            /*  the directory does not exist: require sudo unless it can
+                be created inside a writable parent directory  */
+            if (!(await accessible(path.dirname(dir), fs.constants.W_OK)))
+                return true;
+        }
+        return false;
+    }
+    /*  build the (cmd, args) pair for an "npm" invocation, prefixing
+        with "sudo" when necessary for global operations  */
+    async npmCmd(args, global) {
+        if (global && await this.npmGlobalNeedsSudo()) {
+            const sudo = await which("sudo").catch(() => "");
+            if (sudo !== "") {
+                this.log.write("info", "setup: npm global install root not writable: using \"sudo\"");
+                return { cmd: "sudo", args: ["npm", ...args] };
+            }
+            this.log.write("warning", "setup: npm global install root is not writable by current user " +
+                "and \"sudo\" not found in $PATH: attempting without elevation");
+        }
+        return { cmd: "npm", args };
+    }
+    /*  run a sub-process, suppressing output on success and emitting it on failure  */
+    async run(cmd, args, opts = {}) {
+        const { cwd, quiet = false, retries = 1, ignoreError } = opts;
+        const argsLog = args.map((arg) => arg.replace(/(\w*key=)([^\s&]+)/gi, (_, k, v) => k + "*".repeat(v.length)));
+        this.log.write("info", `setup: $ ${cmd} ${argsLog.join(" ")}` +
+            (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
+        for (let i = 0; i < retries; i++) {
+            const final = (i === retries - 1);
+            try {
+                await execa(cmd, args, { stdio: quiet ? "ignore" : "pipe", cwd });
+                return;
+            }
+            catch (err) {
+                if (!final) {
+                    this.log.write("info", `setup: attempt ${i + 1}/${retries} failed for "${cmd} ${argsLog.join(" ")}": retrying...`);
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                    continue;
+                }
+                if (ignoreError !== undefined) {
+                    this.log.write("info", `setup: ${ignoreError} (skipped)`);
+                    return;
+                }
+                const e = err;
+                const exitCode = typeof e.exitCode === "number" ? e.exitCode : -1;
+                this.log.write("error", `setup: command failed: exit code: ${exitCode}`);
+                if (typeof e.stdout === "string" && e.stdout.length > 0) {
+                    this.log.write("error", "setup: command failed: stdout:");
+                    process.stdout.write(e.stdout);
+                }
+                if (typeof e.stderr === "string" && e.stderr.length > 0) {
+                    this.log.write("error", "setup: command failed: stderr:");
+                    process.stderr.write(e.stderr);
+                }
+                throw err;
+            }
+        }
+    }
+}