@rse/ase 1.0.7 → 2.0.0

package/dst/ase-task-board.js

@@ -0,0 +1,134 @@
+/*
+**  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 { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { ofetch } from "ofetch";
+import { Task } from "./ase-task.js";
+import { loadServiceContext, SERVICE_HOST } from "./ase-service.js";
+import { writeStdout } from "./ase-lib-stdio.js";
+/*  render the lane overview (and the agents passed by the agent relay, if any)
+    as plain text, for use without a terminal  */
+const textOverview = async (log, relay) => {
+    const { buildBoard, cardLabel, editMarker, effortMarker, fetchAgents, busyAgents, agentLabel, agentStatus } = await import("./ase-task-board-core.js");
+    const [board, agents] = await Promise.all([buildBoard(log), fetchAgents(log, relay)]);
+    const busy = busyAgents(agents);
+    const out = [
+        `⧉ ASE: Task Board · project: ${Task.projectIdOf(Task.projectRoot())} · mode: ${board.mode} · tasks: ${board.cards.size}`,
+        ""
+    ];
+    for (const group of board.groups) {
+        out.push(`━ ${group.title}`);
+        for (const lane of group.lanes) {
+            const cards = board.lanes.get(lane.status) ?? [];
+            out.push(`  ${lane.status}${lane.active ? " (active)" : ""} · ${cards.length}`);
+            for (const c of cards) {
+                /*  mark the task (like the terminal board) with the state of its edit requests,
+                    and with its effort size  */
+                const edit = editMarker(c);
+                const size = effortMarker(c);
+                const marks = (edit !== "" ? ` ${edit}` : "") + (size !== "" ? ` ${size}` : "");
+                out.push(`    ${cardLabel(c).replace(c.id, c.id + marks)}` +
+                    (busy.has(c.id) ? ` ⚙ ${busy.get(c.id).map((agent) => agent.name).join(", ")}` : ""));
+            }
+        }
+    }
+    if (agents !== null) {
+        out.push(`━ agents · ${agents.connected ? agents.agents.length : "agent relay unreachable"}`);
+        for (const agent of agents.agents) {
+            const op = agent.recent.at(-1);
+            out.push(`  ${agent.state === "busy" ? "●" : "○"} ${agentLabel(agent)} · ${agentStatus(agent)}`);
+            if (op !== undefined)
+                out.push(`    ${op.task !== "" ? `${op.task}: ` : ""}${op.msg}`);
+        }
+    }
+    for (const w of board.warnings)
+        out.push(`⚠ ${w}`);
+    /*  make the lines safe for the terminal (strip control characters,
+        e.g. in the texts passed by the agent relay)  */
+    return out.map((line) => line.replace(/\p{Cc}/gu, "")).join("\n") + "\n";
+};
+/*  CLI sub-command "ase task board"  */
+export default class TaskBoardCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  ensure the ASE service of the project runs and serves the board, and return its
+        port (a service running other ASE code is never restarted, as this would break
+        the MCP connections of all agent sessions using it)  */
+    async servicePort() {
+        const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
+        await execa(process.execPath, [entry, "service", "start"], { stdin: "ignore" });
+        const port = loadServiceContext(this.log).port;
+        if (port === null)
+            throw new Error("board: ASE service did not report a port");
+        const res = await ofetch.raw(`http://${SERVICE_HOST}:${port}/task-board/api/ping`, { ignoreResponseError: true, timeout: 5 * 1000 }).catch((err) => {
+            throw new Error(`board: ASE service not reachable on port ${port}`, { cause: err });
+        });
+        if (res.status === 404)
+            throw new Error("board: ASE service runs older ASE code without web board " +
+                "(restart it with \"ase service stop\" once no agent session uses it)");
+        const data = res._data;
+        const { BOARD_BUILD } = await import("./ase-task-board-web-server.js");
+        if (data?.build !== BOARD_BUILD)
+            this.log.write("warning", "board: ASE service runs other ASE code " +
+                "(restart it with \"ase service stop\" once no agent session uses it)");
+        return port;
+    }
+    /*  open an URL in the default browser of the platform, waiting only for
+        the opener to spawn, as e.g. "xdg-open" can stay attached to the browser  */
+    async openBrowser(url) {
+        const [cmd, ...args] = process.platform === "darwin" ? ["open", url] :
+            process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+        const opener = execa(cmd, args, { stdio: "ignore", detached: true });
+        const child = opener.nodeChildProcess;
+        await new Promise((resolve) => {
+            child.once("spawn", () => {
+                child.unref();
+                resolve();
+            });
+            opener.catch(() => {
+                this.log.write("warning", `board: cannot open browser, please visit ${url}`);
+                resolve();
+            });
+        });
+    }
+    /*  register CLI sub-command "ase task board"  */
+    register(task) {
+        task
+            .command("board")
+            .description("Show the task board: the lanes of the configured task lifecycle " +
+            "model and the dependency graph of the tasks, following all changes live")
+            .option("-w, --web", "serve the web board through the ASE service of the project " +
+            "and open it in the browser")
+            .option("-t, --text", "print the lane overview as plain text and exit")
+            .option("--agent-relay <url>", "agent relay to receive the live presence of the agents from, " +
+            "as \"ase[s]://<addr>:<port>[/<token>]\" (default: the configured \"project.relay.url\", else none; " +
+            "the web board always follows the configured one)")
+            .action(async (opts) => {
+            /*  serve and open the web board  */
+            if (opts.web === true) {
+                if (opts.agentRelay !== undefined)
+                    this.log.write("warning", "board: \"--agent-relay\" is ignored by the web board, " +
+                        "which follows the configured \"project.relay.url\"");
+                const url = `http://${SERVICE_HOST}:${await this.servicePort()}/task-board`;
+                await writeStdout(`${url}\n`);
+                await this.openBrowser(url);
+                return;
+            }
+            /*  print the plain text overview if requested or without a terminal  */
+            if (opts.text === true || !process.stdout.isTTY || !process.stdin.isTTY) {
+                await writeStdout(await textOverview(this.log, opts.agentRelay));
+                return;
+            }
+            /*  run the interactive terminal board, with the production build of React
+                (its development build records a never cleared performance measure per render)  */
+            process.env.NODE_ENV ??= "production";
+            const { runTUI } = await import("./ase-task-board-tui.js");
+            await runTUI(this.log, opts.agentRelay);
+        });
+    }
+}