@rse/ase 2.0.0 → 2.0.2

package/dst/ase-config-schema.js

@@ -114,6 +114,7 @@ export const configWritableScopes = {
     "project.relay.token": ["user"],
     "project.relay.crt": ["user", "project"],
     "project.relay.key": ["user", "project"],
+    "project.service.port": ["project"],
     "project.artifact.spec.basedir": ["user", "project"],
     "project.artifact.spec.files": ["user", "project"],
     "project.artifact.spec.schema": ["user", "project"],
@@ -255,6 +256,8 @@ const flowSchema = (forms) => v.optional(v.pipe(v.string(), v.check((value) => {
 const minutesSchema = v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+(?:\.\d+)?$/.test(String(s)) && Number(s) > 0, "expected a positive number of minutes")));
 /*  schema for a multiplier of the effort estimation  */
 const multiplierSchema = v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+(?:\.\d+)?$/.test(String(s)) && Number(s) >= 1, "expected a multiplier of at least 1")));
+/*  schema for an unprivileged TCP port number  */
+const portSchema = v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+$/.test(String(s)) && Number(s) >= 1024 && Number(s) <= 65535, "expected a port number (1024-65535)")));
 /*  schema for ".ase/config.yaml"  */
 export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
@@ -290,6 +293,9 @@ export const configSchema = v.nullish(v.strictObject({
             crt: v.optional(v.pipe(v.string(), v.minLength(1))),
             key: v.optional(v.pipe(v.string(), v.minLength(1)))
         })),
+        service: v.optional(v.strictObject({
+            port: portSchema
+        })),
         artifact: v.optional(v.strictObject({
             spec: artifactSpecSchema,
             code: artifactSchema,
@@ -305,7 +311,7 @@ export const configSchema = v.nullish(v.strictObject({
         enabled: v.optional(v.union([v.boolean(), v.picklist(["true", "false"])])),
         implicit: v.optional(v.union([v.boolean(), v.picklist(["true", "false"])])),
         service: v.optional(v.strictObject({
-            port: v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+$/.test(String(s)) && Number(s) >= 1024 && Number(s) <= 65535, "expected a port number (1024-65535)"))),
+            port: portSchema,
             token: v.optional(v.pipe(v.string(), v.minLength(1))),
             interval: v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+$/.test(String(s)), "expected a number of minutes (0 disables)"))),
             idle: v.optional(v.pipe(v.union([v.number(), v.string()]), v.check((s) => /^\d+$/.test(String(s)), "expected a number of minutes (0 disables)")))

package/dst/ase-config.js

@@ -191,7 +191,8 @@ export class ConfigMCP {
                 const cfg = new Config("config", configSchema, this.log, scope);
                 cfg.read();
                 const val = cfg.get(args.key);
-                const text = val === undefined ? "" : JSON.stringify(val);
+                const text = val === undefined ? "" :
+                    JSON.stringify(configSecretKeys.includes(cfg.resolveKey(args.key)) ? "***" : val);
                 return { content: [{ type: "text", text }] };
             }
             catch (err) {

package/dst/ase-hook.js

@@ -16,6 +16,7 @@ import { parseScope, userStateDir } from "./ase-config-scope.js";
 import { readStdin, writeStdout } from "./ase-lib-stdio.js";
 import { Task } from "./ase-task.js";
 import * as TaskFormat from "./ase-task-format.js";
+import { parseTool } from "./ase-setup-common.js";
 const addonMcpServers = [
     "chat-alibaba-qwen",
     "chat-deepseek",
@@ -706,12 +707,6 @@ export default class HookCommand {
         }
         return 0;
     }
-    /*  parse and validate the --tool option  */
-    parseTool(value) {
-        if (value !== "claude" && value !== "copilot" && value !== "codex")
-            throw new Error(`invalid --tool value: "${value}" (expected "claude", "copilot", or "codex")`);
-        return value;
-    }
     /*  register commands  */
     register(program) {
         /*  default for --tool derived from ASE_TOOL environment variable
@@ -743,7 +738,7 @@ export default class HookCommand {
                 .description(desc)
                 .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
                 .action(async (opts) => {
-                process.exitCode = await handler(this.parseTool(opts.tool));
+                process.exitCode = await handler(parseTool(opts.tool));
             });
     }
 }

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

@@ -13,6 +13,7 @@ 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 { writeStdout } from "./ase-lib-stdio.js";
 import { Service } from "./ase-service.js";
 import { DaemonCommand } from "./ase-lib-daemon-cli.js";
 import { urlHost, isLoopback, serverHeader } from "./ase-lib-server-bind.js";
@@ -381,26 +382,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-lib-version.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import updateNotifier from "update-notifier";
+import semver from "semver";
 import pkg from "../package.json" with { type: "json" };
 /*  determination of current and available ASE versions  */
 export default class Version {
@@ -18,9 +19,12 @@ export default class Version {
             pkg,
             updateCheckInterval: 1000 * 60 * 60
         });
-        /*  re-persist the cached update information, as update-notifier consumes it on read  */
-        if (notifier.update !== undefined)
-            notifier.config?.set("update", notifier.update);
-        return notifier.update?.latest ?? Version.current();
+        /*  re-persist the cached 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;
+        if (latest === undefined || !semver.valid(latest) || !semver.gt(latest, Version.current()))
+            return Version.current();
+        notifier.config?.set("update", notifier.update);
+        return latest;
     }
 }

package/dst/ase-service.js

@@ -86,7 +86,7 @@ const LOG_MAX_SIZE = 1024 * 1024;
 const LOG_KEEP_LINES = 2000;
 const LOG_ARGS_MAX = 200;
 /*  load the optional "config.yaml" and "service.yaml" files and derive
-    the service identity context (project id, port, service config)  */
+    the service identity context (project id, port, preferred port, service config)  */
 export const loadServiceContext = (log) => {
     /*  load files  */
     const cfg = new Config("config", configSchema, log);
@@ -97,10 +97,13 @@ export const loadServiceContext = (log) => {
     const projectId = cfg.get("project.id") || Task.projectIdOf(Task.projectRoot());
     /*  determine service port  */
     const port = svc.get("port") ?? null;
+    /*  determine preferred service port  */
+    const pref = cfg.get("project.service.port");
+    const portPref = pref !== null && pref !== undefined ? Number(pref) : null;
     /*  determine path to ".ase" directory  */
     const aseDir = path.dirname(svc.filename);
     /*  return context information  */
-    return { projectId, port, svc, aseDir };
+    return { projectId, port, portPref, svc, aseDir };
 };
 /*  reusable functionality: port allocation, persistence, and process spawning  */
 export class Service {
@@ -117,8 +120,11 @@ export class Service {
             s.listen(port, HOST);
         });
     }
-    /*  allocate a fresh random port in PORT_MIN..PORT_MAX  */
-    static async allocatePort() {
+    /*  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 Service.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 Service.tryBind(p))
@@ -588,6 +594,13 @@ export default class ServiceCommand {
             }
         }, TICK_MS).unref();
     }
+    /*  allocate the service port, preferring the configured one, else falling back to a random one  */
+    async allocatePort(ctx) {
+        const port = await Service.allocatePort(ctx.portPref);
+        if (ctx.portPref !== null && port !== ctx.portPref)
+            this.log.write("warning", `service: preferred port ${ctx.portPref} unavailable, falling back to port ${port}`);
+        return port;
+    }
     /*  start flow: ensure port, probe, optionally detach (or run in the foreground)  */
     async doStart(opts = {}) {
         const ctx = this.loadContext();
@@ -614,7 +627,7 @@ export default class ServiceCommand {
         }
         /*  run the service in the foreground, logging to the terminal and without idle timeout  */
         if (opts.foreground) {
-            port = await Service.allocatePort();
+            port = await this.allocatePort(ctx);
             await this.runService({ ...ctx, port }, true);
             return await new Promise(() => { });
         }
@@ -622,7 +635,7 @@ export default class ServiceCommand {
             re-allocate, re-spawn; early-break on foreign listener  */
         let lastErr = new Error("service failed to start within timeout");
         for (let attempt = 0; attempt < 3; attempt++) {
-            port = await Service.allocatePort();
+            port = await this.allocatePort(ctx);
             const { child, logFile } = Service.spawnDetached(ctx.aseDir, port, this.log.logLevel());
             let exited = false;
             let exitCode = null;

package/dst/ase-task-board-core.js

@@ -187,7 +187,7 @@ export class BoardState {
             state[surface][flag] = !state[surface][flag];
         });
     }
-    /*  set the shown view (lanes, graph, stats, or agents)  */
+    /*  set the shown view (lanes, graph, stats, agents, or flow)  */
     static setView(surface, view) {
         return BoardState.update((state) => {
             state[surface].view = view;

package/dst/ase-task-board-tui-control.js

@@ -310,16 +310,6 @@ const handlePopupKey = (ctx, input, key) => {
             setPrompt({ ...prompt, focus: prompt.focus === "request" ? "cancel" : "request" });
         return;
     }
-    /*  type the prompt of an edit request: RETURN requests the edit, Shift+RETURN
-        (under the kitty keyboard protocol only), Alt+RETURN (under the kitty keyboard
-        protocol, or where the terminal sends it as ESC+RETURN, e.g. with "Option as Meta"
-        on macOS), and Ctrl+J (in every terminal, as a plain linefeed without the kitty
-        keyboard protocol) insert a newline,
-        the left/right arrows move the cursor by one character, HOME/END move it
-        to the start/end, BACKSPACE removes the character before the cursor, DELETE
-        removes the character at the cursor, and all other input (also pasted text,
-        with its newlines kept and its other control characters turned into spaces)
-        is inserted at the cursor  */
     if (prompt !== null && prompt.request !== null && prompt.focus === "name") {
         /*  type the request name of a request by prompt: RETURN switches to the prompt (resp. to
             the request button if the prompt is ignored), the
@@ -342,6 +332,16 @@ const handlePopupKey = (ctx, input, key) => {
             name(request.name + input.toLowerCase());
         return;
     }
+    /*  type the prompt of an edit request: RETURN requests the edit, Shift+RETURN
+        (under the kitty keyboard protocol only), Alt+RETURN (under the kitty keyboard
+        protocol, or where the terminal sends it as ESC+RETURN, e.g. with "Option as Meta"
+        on macOS), and Ctrl+J (in every terminal, as a plain linefeed without the kitty
+        keyboard protocol) insert a newline,
+        the left/right arrows move the cursor by one character, HOME/END move it
+        to the start/end, BACKSPACE removes the character before the cursor, DELETE
+        removes the character at the cursor, and all other input (also pasted text,
+        with its newlines kept and its other control characters turned into spaces)
+        is inserted at the cursor  */
     if (prompt !== null) {
         const chars = [...prompt.text];
         const pos = Math.max(0, Math.min(prompt.pos, chars.length));

package/dst/ase-task-board-tui-model.js

@@ -161,6 +161,14 @@ const boxAt = (map, mx, my) => {
     }
     return undefined;
 };
+/*  the box of every node of a laid out graph, for the spatial navigation and the scrolling  */
+const placesOf = (graph) => {
+    const map = new Map();
+    if (graph !== undefined)
+        for (const n of graph.nodes.values())
+            map.set(n.id, { r: n.y + Math.floor(n.h / 2), c: n.x + Math.floor(n.w / 2), top: n.y, bottom: n.y + n.h - 1, bl: n.x, br: n.x + n.w - 1 });
+    return map;
+};
 /*  the state of the agents view: the agents of the master list, the selected one (followed by its id,
     else, until explicitly selected again, the one at the index of the previously selected one),
     the lines of its operation pane, and the lines of its recent processing log in the detail view (within its frame), scrolled
@@ -343,13 +351,7 @@ export const useBoardState = (log, initial, relay) => {
         }
     }, [all, prompt]);
     /*  remember the box of every graph node for the spatial navigation and the scrolling  */
-    const places = React.useMemo(() => {
-        const map = new Map();
-        if (layout !== null)
-            for (const n of layout.graph.nodes.values())
-                map.set(n.id, { r: n.y + Math.floor(n.h / 2), c: n.x + Math.floor(n.w / 2), top: n.y, bottom: n.y + n.h - 1, bl: n.x, br: n.x + n.w - 1 });
-        return map;
-    }, [layout]);
+    const places = React.useMemo(() => placesOf(layout?.graph), [layout]);
     /*  follow changes of the task storage and of the lifecycle mode,
         and the kind and connection state of the task store
         (in the background, i.e. without the busy popup)  */
@@ -416,13 +418,7 @@ export const useBoardState = (log, initial, relay) => {
         if (!flow.cards.has(flowSel) && !flow.states.some((s) => flowState(s) === flowSel) && flow.cards.size > 0)
             setFlowSel(flow.cards.keys().next().value);
     }, [flow, flowSel]);
-    const flowPlaces = React.useMemo(() => {
-        const map = new Map();
-        if (flowLayout !== null)
-            for (const n of flowLayout.graph.nodes.values())
-                map.set(n.id, { r: n.y + Math.floor(n.h / 2), c: n.x + Math.floor(n.w / 2), top: n.y, bottom: n.y + n.h - 1, bl: n.x, br: n.x + n.w - 1 });
-        return map;
-    }, [flowLayout]);
+    const flowPlaces = React.useMemo(() => placesOf(flowLayout?.graph), [flowLayout]);
     /*  fetch the AI usage of all tasks whenever the statistics view is shown or the board
         changes, but only while the statistics view is shown (as each fetching loads all
         plans), and once known in the background, i.e. without the busy popup  */

package/dst/ase-task-board-tui-view.js

@@ -21,6 +21,10 @@ const GRID_MIN = 30;
 const GRID_GAP = 1;
 /*  make a text of the agent relay safe for the terminal (strip control characters)  */
 const clean = (text) => text.replace(/\p{Cc}/gu, "");
+/*  append to the content of an info line (" " if empty) the hint how to show the
+    hidden key hints again, so it need not be remembered while the key hints are hidden  */
+const keysHint = (surface, info) => surface.keys ? info : info === " " ? "?: show key hints" :
+    [...(Array.isArray(info) ? info : [info]), " · ?: show key hints"];
 /*  compute the visible group range starting at a first group, with the
     width of each visible group (collapsed groups stay narrow, expanded
     groups share the remaining width but never drop below the minimum)  */
@@ -331,7 +335,8 @@ export const renderLanes = (ctx) => {
     const arrows = shown < total && !grown;
     const group = board.groups[sel.g];
     const info = grown ? `lane ${group.lanes[sel.l].status} of group ${group.title} grown · g shrinks` :
-        `groups ${fit.first + 1}–${fit.last + 1} of ${total} · ${arrows ? "←/→ scrolls" : "all visible"}`;
+        `groups ${fit.first + 1}–${fit.last + 1} of ${total} · ${arrows ? "←/→ scrolls" : "all visible"}` +
+            (surface.keys ? "" : " · ?: show key hints");
     const view = { board, surface, sel, dim, carry, titles: surface.titles, scroll: { left: -1, right: -1 }, pulse, cardRef, laneRef, groupRef, agents, working };
     /*  the scroll bar consumes the entire width remaining besides the info  */
     const track = Math.max(1, columns - 2 - info.length - 3);
@@ -390,8 +395,8 @@ export const renderGraph = (ctx) => {
         })))))), 
         /*  overlay the graph statistics centered onto the top border  */
         h(Box, { position: "absolute", top: 0, left: 0, width: "100%", justifyContent: "center" }, h(Text, { ...cx("dim", dim && "dimmed"), wrap: "truncate" }, `[ ${board.cards.size} tasks, ${deps} dependencies ]`))),
-        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), card === undefined ? " " :
-            ["task: ", h(Text, { key: "id", ...cx("bold") }, card.id), " · status: ", h(Text, { key: "status", ...cx("bold") }, card.status)])),
+        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), keysHint(surface, card === undefined ? " " :
+            ["task: ", h(Text, { key: "id", ...cx("bold") }, card.id), " · status: ", h(Text, { key: "status", ...cx("bold") }, card.status)]))),
         h(Box, { key: "keys1", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), "↑/↓/←/→/Left-Click: select task · ⏎/Double-Click: view task · e: edit task · T: transition task")),
         h(Box, { key: "keys2", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), `D: delete task · A: assign task · E: edit by prompt · R: request by prompt · N: new task · t: ${graphTitles ? "collapse" : "expand"} titles · ` +
             `s: ${surface.standalone ? "hide" : "show"} standalone tasks`)),
@@ -434,7 +439,7 @@ export const renderFlow = (ctx) => {
         })))))), 
         /*  overlay the graph statistics centered onto the top border  */
         h(Box, { position: "absolute", top: 0, left: 0, width: "100%", justifyContent: "center" }, h(Text, { ...cx("dim", dim && "dimmed"), wrap: "truncate" }, `[ ${agents?.agents.length ?? 0} agents, ${flow.states.length} states ]`))),
-        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), rel !== null ? [
+        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), keysHint(ctx.surface, rel !== null ? [
             "state: ", h(Text, { key: "state", ...cx("bold") }, rel.state),
             " · observed by: ", h(Text, { key: "in", ...cx("bold") }, names(rel.input)),
             " · written by: ", h(Text, { key: "out", ...cx("bold") }, names(rel.output)),
@@ -448,7 +453,7 @@ export const renderFlow = (ctx) => {
                 " · output: ", h(Text, { key: "out", ...cx("bold") }, states.output.join(", ") || "none"),
                 ...(states.gate !== undefined ? [" · gate: ", h(Text, { key: "gate", ...cx("bold") }, states.gate)] : [])
             ])
-        ])),
+        ]))),
         h(Box, { key: "keys1", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), "↑/↓/←/→/Left-Click: select agent/state · ⏎/Double-Click: view agent · " +
             "⇈/⇊/⇤/⇥/Wheel: scroll canvas")),
         h(Box, { key: "keys2", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), `v/V: ${viewCycleHint("flow", agents !== null)} · M: ${mouse ? "disable" : "enable"} mouse · ?: hide key hints · q: quit`))
@@ -554,12 +559,12 @@ export const renderAgents = (ctx) => {
     const detail = h(Box, { key: "detail", flexGrow: 1, height: boardH, marginLeft: 1, flexDirection: "column" }, op, info, log);
     return [
         h(Box, { key: "agents", height: boardH, paddingX: 1 }, master, detail),
-        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", "truncate", dim && "dimmed"), agent === undefined ? " " : [
+        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", "truncate", dim && "dimmed"), keysHint(ctx.surface, agent === undefined ? " " : [
             "agent: ", h(Text, { key: "agent", ...cx("bold") }, clean(agentLabel(agent))),
             ...(agentOp.title !== "" ? [
                 " · operation: ", h(Text, { key: "op", ...cx("bold") }, agentOp.title)
             ] : [])
-        ])),
+        ]))),
         h(Box, { key: "keys1", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), "↑/↓/Left-Click: select agent · ⇈/⇊/⇤/⇥: page/top/bottom agent log · Mouse-Wheel: scroll agent log")),
         h(Box, { key: "keys2", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), `v/V: ${viewCycleHint("agents", agents !== null)} · M: ${mouse ? "disable" : "enable"} mouse · ?: hide key hints · q: quit`))
     ];
@@ -839,8 +844,8 @@ export const renderStats = (ctx) => {
     const shown = stats.states.reduce((n, s) => n + s.count, 0);
     return [
         h(Box, { key: "stats", height: boardH, paddingX: 1, flexDirection: "column", overflow: "hidden" }, ranges, chart, progress, usages, tops),
-        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), ["statistics of ", h(Text, { key: "n", ...cx("bold") }, String(shown)),
-            ` ${filter !== "" ? "filtered " : ""}tasks`, ...(range !== "total" ? [" ", h(Text, { key: "r", ...cx("bold") }, statsRangeLabels[range])] : [])])),
+        h(Box, { key: "info", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), keysHint(ctx.surface, ["statistics of ", h(Text, { key: "n", ...cx("bold") }, String(shown)),
+            ` ${filter !== "" ? "filtered " : ""}tasks`, ...(range !== "total" ? [" ", h(Text, { key: "r", ...cx("bold") }, statsRangeLabels[range])] : [])]))),
         h(Box, { key: "keys1", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), `←/→: select time range · /: filter tasks · v/V: ${viewCycleHint("stats", agents !== null)}`)),
         h(Box, { key: "keys2", ...cx("bar") }, h(Text, cx("hint", dim && "dimmed"), `M: ${mouse ? "disable" : "enable"} mouse · ?: hide key hints · q: quit`))
     ];