@rse/ase 1.0.7 → 2.0.0

package/dst/ase-hook.js

@@ -9,9 +9,13 @@ import os from "node:os";
 import { execaSync } from "execa";
 import { quote } from "shell-quote";
 import * as v from "valibot";
-import Version from "./ase-version.js";
-import { Config, configSchema, parseScope } from "./ase-config.js";
-import { readStdin, writeStdout } from "./ase-stdio.js";
+import Version from "./ase-lib-version.js";
+import { Config, sessionState } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
+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";
 const addonMcpServers = [
     "chat-alibaba-qwen",
     "chat-deepseek",
@@ -88,12 +92,13 @@ export default class HookCommand {
     }
     /*  resolve the base directory holding all per-session state  */
     sessionBaseDir() {
-        return path.join(os.homedir(), ".ase", "session");
+        return path.join(userStateDir(), "session");
     }
     /*  garbage-collect orphaned session directories left behind by agents
         which died before their session-end hook could run; a live session
-        keeps its directory's mtime current, as every tool call acquires a
-        lock file inside it, so plain age is a reliable liveness signal  */
+        usually refreshes its directory's mtime, as its locked configuration
+        accesses create lock files inside it, so plain age is a sufficient
+        liveness heuristic  */
     pruneStaleSessions(currentSessionId) {
         const base = this.sessionBaseDir();
         let entries;
@@ -198,42 +203,20 @@ export default class HookCommand {
             return "";
         }
     }
-    /*  handler for "ase hook session-start" (all tools)  */
-    async doSessionStart(tool) {
-        /*  determine plugin root (env var name differs per tool)  */
-        const pluginRoot = this.pluginRoot(tool);
-        /*  determine path to external files  */
-        const filePkg = path.join(pluginRoot, ".claude-plugin", "plugin.json");
-        const fileMd = path.join(pluginRoot, "meta", "ase-constitution.md");
-        const fileStyle = path.join(pluginRoot, "output-styles", "ase-terse.md");
-        /*  read external files  */
-        let pkg;
-        let md;
-        let style;
+    /*  read a plugin file, throwing a descriptive error on failure  */
+    readPluginFile(file, what) {
         try {
-            pkg = fs.readFileSync(filePkg, "utf8");
+            return fs.readFileSync(file, "utf8");
         }
         catch (err) {
-            throw new Error(`failed to read plugin manifest: ${filePkg}`, { cause: err });
-        }
-        try {
-            md = fs.readFileSync(fileMd, "utf8");
+            throw new Error(`failed to read ${what}: ${file}`, { cause: err });
         }
-        catch (err) {
-            throw new Error(`failed to read constitution file: ${fileMd}`, { cause: err });
-        }
-        try {
-            style = fs.readFileSync(fileStyle, "utf8");
-        }
-        catch (err) {
-            throw new Error(`failed to read output style file: ${fileStyle}`, { cause: err });
-        }
-        /*  determine own version  */
-        const pkgObj = this.parseJSON(pkg, v.object({ version: v.optional(v.string()) }));
-        const versionCurrentPlugin = pkgObj.version ?? "";
+    }
+    /*  determine the version hint on a tool/plugin version mismatch,
+        an available tool update, and a development setup  */
+    async versionHint(versionCurrentPlugin) {
         const versionCurrentTool = Version.current();
         const versionLatestTool = await Version.latest();
-        /*  sanity check situation  */
         const versionHints = [];
         if (versionCurrentPlugin !== versionCurrentTool)
             versionHints.push("**WARNING:** version *mismatch*: " +
@@ -242,7 +225,81 @@ export default class HookCommand {
             versionHints.push(`**NOTICE:** *latest* version: **${versionLatestTool}**, please update!`);
         if (process.env.ASE_SETUP_DEV !== undefined)
             versionHints.push("**NOTICE:** *development* setup");
-        const versionHint = versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
+        return versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
+    }
+    /*  switch to the project directory announced in the event payload: GitHub
+        Copilot CLI runs its hooks in the plugin installation directory, so
+        every working-directory-relative lookup -- most notably the layered
+        configuration files -- would otherwise miss the project entirely  */
+    switchDir(dir) {
+        if (dir === undefined || dir === "")
+            return;
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+            this.log.write("warning", `hook: ignoring invalid project directory: ${dir}`);
+            return;
+        }
+        process.chdir(dir);
+    }
+    /*  determine the project directory: the Git top-level directory of "cwd",
+        or "cwd" itself when outside a Git working tree  */
+    determineProjectDir(cwd) {
+        let projectDir = cwd;
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
+                stderr: "ignore", cwd
+            });
+            if (result.stdout.trim() !== "")
+                projectDir = result.stdout.trim();
+        }
+        catch {
+            /*  not inside a Git working tree  */
+        }
+        return projectDir;
+    }
+    /*  determine the project id: the valid configured "project.id", or else
+        the id derived from the already resolved project directory  */
+    determineProjectId(projectDir, cfg) {
+        let configuredId = String(cfg.get("project.id") ?? "");
+        if (configuredId !== "" && !TaskFormat.ID_RE.test(configuredId)) {
+            this.log.write("warning", `hook: ignoring invalid configured "project.id" "${configuredId}" ` +
+                "(must match [A-Za-z0-9_-]+)");
+            configuredId = "";
+        }
+        return configuredId || Task.projectIdOf(projectDir);
+    }
+    /*  append environment variable exports to the environment file of
+        Anthropic Claude Code CLI (the other tools have no equivalent mechanism)  */
+    writeEnvFile(tool, vars) {
+        const envFile = tool === "claude" ? (process.env.CLAUDE_ENV_FILE ?? "") : "";
+        if (envFile === "")
+            return;
+        const script = Object.entries(vars)
+            .map(([name, value]) => `export ${name}=${quote([value])}\n`)
+            .join("");
+        try {
+            fs.appendFileSync(envFile, script, "utf8");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.log.write("warning", `hook: failed to write environment file: ${message}`);
+        }
+    }
+    /*  handler for "ase hook session-start" (all tools)  */
+    async doSessionStart(tool) {
+        /*  determine plugin root (env var name differs per tool)  */
+        const pluginRoot = this.pluginRoot(tool);
+        /*  determine path to external files  */
+        const filePkg = path.join(pluginRoot, ".claude-plugin", "plugin.json");
+        const fileMd = path.join(pluginRoot, "meta", "ase-constitution.md");
+        const fileStyle = path.join(pluginRoot, "output-styles", "ase-terse.md");
+        /*  read external files  */
+        const pkg = this.readPluginFile(filePkg, "plugin manifest");
+        const md = this.readPluginFile(fileMd, "constitution file");
+        const style = this.readPluginFile(fileStyle, "output style file");
+        /*  determine own version  */
+        const pkgObj = this.parseJSON(pkg, v.object({ version: v.optional(v.string()) }));
+        const versionCurrentPlugin = pkgObj.version ?? "";
+        const versionHint = await this.versionHint(versionCurrentPlugin);
         /*  read session information (Anthropic Claude Code CLI uses snake_case fields,
             GitHub Copilot CLI uses camelCase fields)  */
         const stdin = await readStdin().catch(() => "");
@@ -253,36 +310,48 @@ export default class HookCommand {
         }));
         /*  determine session id  */
         const sessionId = this.pickSessionId(input);
+        /*  adopt the project directory before any context is derived from the
+            working directory, especially the layered configuration below
+            (GitHub Copilot CLI only -- the other tools already run their
+            hooks inside the project directory)  */
+        if (tool === "copilot")
+            this.switchDir(input.cwd);
         /*  garbage-collect orphaned session directories of previous agent runs  */
         this.pruneStaleSessions(sessionId);
         /*  establish config context (session-scoped only if a valid sessionId is present)  */
         const hasSession = this.isValidSessionId(sessionId);
         const cfg = new Config("config", configSchema, this.log, hasSession ? parseScope(`session:${sessionId}`) : parseScope(undefined));
-        /*  determine task id (only persist when scoped to a real session)  */
+        /*  determine the project directory, persisted below, because for GitHub Copilot
+            CLI it is the single piece of context this agent tool withholds from the MCP
+            server: it starts the MCP server in the plugin installation directory, long
+            before this hook runs, so the server can only learn it from here (and for all
+            agent tools, the project service determines the sessions of its project by it,
+            in order to attach them to the usage windows of their tasks assigned elsewhere)  */
+        const projectDir = this.determineProjectDir(input.cwd ?? process.cwd());
+        cfg.read();
+        /*  determine headless mode  */
+        const headless = process.env.ASE_HEADLESS === "true" ? "true" : "false";
+        /*  determine task id and persist it, together with the project directory
+            (see above) and the headless mode (as the project service never attaches
+            the headless sessions of the agents, which book their usage themselves, to
+            usage windows), into the internal session state (only when scoped to a real
+            session), normalizing the path separators of the project directory, as Git
+            reports the top-level directory with forward slashes even on Windows  */
         const taskId = process.env.ASE_TASK_ID ?? "default";
-        cfg.lock(() => {
-            cfg.read();
-            if (hasSession) {
-                cfg.set("agent.task", taskId);
-                cfg.write();
-            }
-        });
+        if (hasSession) {
+            const state = sessionState(this.log, sessionId);
+            state.lock(() => {
+                state.read();
+                state.set("task", taskId);
+                state.set("basedir", path.resolve(projectDir));
+                state.set("headless", headless);
+                state.write();
+            });
+        }
         /*  initialize agent activity status  */
         this.writeAgentStatus("ready");
         /*  determine project id  */
-        const cwd = input.cwd ?? process.cwd();
-        let projectDir = cwd;
-        try {
-            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
-                stderr: "ignore", cwd
-            });
-            if (result.stdout.trim() !== "")
-                projectDir = result.stdout.trim();
-        }
-        catch {
-            /*  not inside a Git working tree  */
-        }
-        const projectId = path.basename(projectDir);
+        const projectId = this.determineProjectId(projectDir, cfg);
         /*  determine user id  */
         const userId = process.env.USER ?? process.env.LOGNAME ?? "unknown";
         /*  helper function: determine a setting from the explicitly configured
@@ -293,64 +362,100 @@ export default class HookCommand {
             const val = cfg.getExplicit(key);
             return typeof val === "string" ? val : (process.env[envVar] ?? dflt);
         };
-        /*  determine agent persona style, agent guidance level, and project boxing transparency  */
+        /*  determine agent persona style, agent guidance level, project
+            boxing transparency, and project task lifecycle  */
         const persona = setting("agent.persona", "ASE_PERSONA_STYLE", "engineer");
         const guidance = setting("agent.guidance", "ASE_GUIDANCE_LEVEL", "normal");
         const boxing = setting("project.boxing", "ASE_PROJECT_BOXING", "white");
+        const lifecycle = setting("project.task.lifecycle", "ASE_PROJECT_TASK_LIFECYCLE", "solo");
+        /*  determine the defaults of the change set flow keys of the task plans  */
+        const defaultSource = setting("project.task.default.source", "ASE_PROJECT_TASK_DEFAULT_SOURCE", "worktree");
+        const defaultChangeset = setting("project.task.default.changeset", "ASE_PROJECT_TASK_DEFAULT_CHANGESET", "worktree");
+        const defaultTarget = setting("project.task.default.target", "ASE_PROJECT_TASK_DEFAULT_TARGET", "source");
         /*  determine the specification base directory and the whitespace-separated
             list of SpecBook schema configurations (empty: the bundled standard schema)  */
         const specBasedir = String(cfg.get("project.artifact.spec.basedir") ?? "");
         const specSchema = String(cfg.get("project.artifact.spec.schema") ?? "");
-        /*  determine headless mode  */
-        const headless = process.env.ASE_HEADLESS === "true" ? "true" : "false";
+        /*  publish the ASE session information and emit it as the hook output payload  */
+        const payload = this.publishSessionInfo(tool, {
+            version: versionCurrentPlugin, versionHint, pluginRoot, persona, guidance, userId, projectId,
+            boxing, lifecycle, defaultSource, defaultChangeset, defaultTarget,
+            specBasedir, specSchema, taskId, sessionId, headless
+        }, md, path.dirname(fileMd), style);
+        await writeStdout(JSON.stringify(payload));
+        return 0;
+    }
+    /*  handler for "ase hook session-persona" (all tools): inject the persona rules
+        as a separate hook output, as agent tools like Anthropic Claude Code CLI
+        persist any hook output beyond 10,000 characters to a file and only show a preview  */
+    async doSessionPersona(tool) {
+        /*  read persona file  */
+        const pluginRoot = this.pluginRoot(tool);
+        const persona = this.readPluginFile(path.join(pluginRoot, "meta", "ase-persona.md"), "persona file");
+        /*  inject markdown into session context (same nesting as for "session-start")  */
+        const payload = tool !== "copilot" ? {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": persona
+            }
+        } : {
+            "additionalContext": persona
+        };
+        await writeStdout(JSON.stringify(payload));
+        return 0;
+    }
+    /*  publish the ASE session information: export it to the shell commands and
+        render it, together with the constitution markdown, the output style, and
+        the deterministic ASE banner, into the "session-start" hook output payload  */
+    publishSessionInfo(tool, info, md, mdDir, style) {
+        const { version, versionHint, pluginRoot, persona, guidance, userId, projectId, boxing, lifecycle, defaultSource, defaultChangeset, defaultTarget, specBasedir, specSchema, taskId, sessionId, headless } = info;
         /*  provide ASE information to Anthropic Claude Code CLI shell commands
             (Anthropic Claude Code CLI only -- GitHub Copilot CLI has no equivalent mechanism)  */
-        const envFile = tool === "claude" ? (process.env.CLAUDE_ENV_FILE ?? "") : "";
-        if (envFile !== "") {
-            const script = `export ASE_VERSION=${quote([versionCurrentPlugin])}\n` +
-                `export ASE_PLUGIN_ROOT=${quote([pluginRoot])}\n` +
-                `export ASE_USER_ID=${quote([userId])}\n` +
-                `export ASE_PROJECT_ID=${quote([projectId])}\n` +
-                `export ASE_PROJECT_BOXING=${quote([boxing])}\n` +
-                `export ASE_SPEC_BASEDIR=${quote([specBasedir])}\n` +
-                `export ASE_SPEC_SCHEMA=${quote([specSchema])}\n` +
-                `export ASE_TASK_ID=${quote([taskId])}\n` +
-                `export ASE_SESSION_ID=${quote([sessionId])}\n` +
-                `export ASE_HEADLESS=${quote([headless])}\n` +
-                `export ASE_AGENT_TOOL=${quote([tool])}\n`;
-            try {
-                fs.appendFileSync(envFile, script, "utf8");
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                this.log.write("warning", `hook: failed to write environment file: ${message}`);
-            }
-        }
+        this.writeEnvFile(tool, {
+            ASE_VERSION: version,
+            ASE_PLUGIN_ROOT: pluginRoot,
+            ASE_USER_ID: userId,
+            ASE_PROJECT_ID: projectId,
+            ASE_PROJECT_BOXING: boxing,
+            ASE_PROJECT_TASK_LIFECYCLE: lifecycle,
+            ASE_PROJECT_TASK_DEFAULT_SOURCE: defaultSource,
+            ASE_PROJECT_TASK_DEFAULT_CHANGESET: defaultChangeset,
+            ASE_PROJECT_TASK_DEFAULT_TARGET: defaultTarget,
+            ASE_SPEC_BASEDIR: specBasedir,
+            ASE_SPEC_SCHEMA: specSchema,
+            ASE_TASK_ID: taskId,
+            ASE_SESSION_ID: sessionId,
+            ASE_HEADLESS: headless,
+            ASE_AGENT_TOOL: tool
+        });
         /*  prepend ASE information to constitution markdown  */
-        md =
-            `<ase-version>${versionCurrentPlugin}</ase-version>\n` +
-                `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
-                `<ase-plugin-root>${pluginRoot}</ase-plugin-root>\n` +
-                `<ase-persona-style>${persona}</ase-persona-style>\n` +
-                `<ase-guidance-level>${guidance}</ase-guidance-level>\n` +
-                `<ase-user-id>${userId}</ase-user-id>\n` +
-                `<ase-project-id>${projectId}</ase-project-id>\n` +
-                `<ase-project-boxing>${boxing}</ase-project-boxing>\n` +
-                `<ase-spec-basedir>${specBasedir}</ase-spec-basedir>\n` +
-                `<ase-spec-schema>${specSchema}</ase-spec-schema>\n` +
-                `<ase-task-id>${taskId}</ase-task-id>\n` +
-                `<ase-session-id>${sessionId}</ase-session-id>\n` +
-                `<ase-headless>${headless}</ase-headless>\n` +
-                `<ase-agent-tool>${tool}</ase-agent-tool>\n` +
-                "\n" + md;
+        let context = `<ase-version>${version}</ase-version>\n` +
+            `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
+            `<ase-plugin-root>${pluginRoot}</ase-plugin-root>\n` +
+            `<ase-persona-style>${persona}</ase-persona-style>\n` +
+            `<ase-guidance-level>${guidance}</ase-guidance-level>\n` +
+            `<ase-user-id>${userId}</ase-user-id>\n` +
+            `<ase-project-id>${projectId}</ase-project-id>\n` +
+            `<ase-project-boxing>${boxing}</ase-project-boxing>\n` +
+            `<ase-project-task-lifecycle>${lifecycle}</ase-project-task-lifecycle>\n` +
+            `<ase-project-task-default-source>${defaultSource}</ase-project-task-default-source>\n` +
+            `<ase-project-task-default-changeset>${defaultChangeset}</ase-project-task-default-changeset>\n` +
+            `<ase-project-task-default-target>${defaultTarget}</ase-project-task-default-target>\n` +
+            `<ase-spec-basedir>${specBasedir}</ase-spec-basedir>\n` +
+            `<ase-spec-schema>${specSchema}</ase-spec-schema>\n` +
+            `<ase-task-id>${taskId}</ase-task-id>\n` +
+            `<ase-session-id>${sessionId}</ase-session-id>\n` +
+            `<ase-headless>${headless}</ase-headless>\n` +
+            `<ase-agent-tool>${tool}</ase-agent-tool>\n` +
+            "\n" + md;
         /*  expand all @<file> references manually  */
-        md = this.expandReferences(md, path.dirname(fileMd));
+        context = this.expandReferences(context, mdDir);
         /*  append the output style to the constitution markdown (GitHub
             Copilot CLI and OpenAI Codex CLI only -- Anthropic Claude Code CLI
             applies the plugin output style natively), stripping the
             YAML frontmatter which only Anthropic Claude Code CLI understands  */
         if (tool !== "claude")
-            md += "\n" + style.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+            context += "\n" + style.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
         /*  build the deterministic ASE banner (rendered directly by the
             agent harness, independent of any model decision, so it is
             guaranteed to appear once in every non-headless session;
@@ -358,7 +463,7 @@ export default class HookCommand {
             "systemMessage" field for this -- GitHub Copilot CLI has no equivalent);
             the trailing help hint is emitted only if the guidance level asks for it  */
         const banner = "\n" +
-            `\n⧉ ASE: ⎈ version: ${versionCurrentPlugin}${versionHint !== "" ? " " + versionHint.replace(/\*/g, "") : ""}` +
+            `\n⧉ ASE: ⎈ version: ${version}${versionHint !== "" ? " " + versionHint.replace(/\*/g, "") : ""}` +
             `\n⧉ ASE: ※ user: ${userId}, ⚑ project: ${projectId}` +
             `\n⧉ ASE: ◉ task: ${taskId}, ⏻ session: ${sessionId}` +
             `\n⧉ ASE: ☯ persona: ${persona}, ▶ guidance: ${guidance}, ▢ boxing: ${boxing}` +
@@ -373,10 +478,10 @@ export default class HookCommand {
         const payload = tool !== "copilot" ? {
             "hookSpecificOutput": {
                 "hookEventName": "SessionStart",
-                "additionalContext": md
+                "additionalContext": context
             }
         } : {
-            "additionalContext": md
+            "additionalContext": context
         };
         /*  attach the deterministic banner as a top-level "systemMessage"
             (only for the harnesses that support it and only when not
@@ -385,8 +490,7 @@ export default class HookCommand {
             by letting the model emit the banner itself)  */
         if ((tool === "claude" || tool === "codex") && headless !== "true" && guidance !== "none")
             payload.systemMessage = banner;
-        await writeStdout(JSON.stringify(payload));
-        return 0;
+        return payload;
     }
     /*  publish the agent activity marker to tmux as a per-pane user
         option, so tmux can render the live state via
@@ -420,7 +524,7 @@ export default class HookCommand {
     async doSessionEnd(_tool) {
         /*  determine session id  */
         const sessionId = await this.readSessionIdFromStdin();
-        /*  remove the session directory ~/.ase/session/<id> (only for a valid sessionId)  */
+        /*  remove the session directory <state-dir>/session/<id> (only for a valid sessionId)  */
         if (this.isValidSessionId(sessionId)) {
             const dir = path.join(this.sessionBaseDir(), sessionId);
             try {
@@ -429,6 +533,18 @@ export default class HookCommand {
             catch (_e) {
                 /*  best-effort: ignore failures  */
             }
+            /*  detach the session from its AI usage window (if any), which closes
+                and books the window once no other session remains attached to it
+                (noting the session end and starting the owning project service in the
+                background, if it is not reachable in time, and imported dynamically
+                to keep it out of all other hooks)  */
+            try {
+                const { UsageTracker } = await import("./ase-service-otel.js");
+                await UsageTracker.detachRemote(sessionId);
+            }
+            catch (err) {
+                this.log.write("warning", `hook: failed to detach session from its usage window: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
         return 0;
     }
@@ -446,16 +562,16 @@ export default class HookCommand {
         }));
         return this.pickSessionId(input);
     }
-    /*  read the session-scoped "agent.skill" config value  */
+    /*  read the "skill" value of the internal session state  */
     readActiveSkill(sessionId) {
         if (!this.isValidSessionId(sessionId))
             return "";
         try {
-            const cfg = new Config("config", configSchema, this.log, parseScope(`session:${sessionId}`));
+            const state = sessionState(this.log, sessionId);
             let val = "";
-            cfg.lock(() => {
-                cfg.read();
-                const skill = cfg.get("agent.skill");
+            state.lock(() => {
+                state.read();
+                const skill = state.get("skill");
                 if (typeof skill === "string")
                     val = skill;
             });
@@ -614,6 +730,7 @@ export default class HookCommand {
         /*  register CLI sub-commands "ase hook <event>"  */
         const subCmds = [
             { name: "session-start", desc: "handle SessionStart hook event", handler: (tool) => this.doSessionStart(tool) },
+            { name: "session-persona", desc: "handle SessionStart hook event (persona)", handler: (tool) => this.doSessionPersona(tool) },
             { name: "session-end", desc: "handle SessionEnd hook event", handler: (tool) => this.doSessionEnd(tool) },
             { name: "pre-tool-use", desc: "handle tool PreToolUse hook event", handler: (tool) => this.doPreToolUse(tool) },
             { name: "permission-request", desc: "handle tool PermissionRequest hook event", handler: (tool) => this.doPermissionRequest(tool) },

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

@@ -0,0 +1,130 @@
+/*
+**  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 { spawn } from "node:child_process";
+import { Service } from "./ase-service.js";
+/*  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,
+    shows its log file, and stops it, where the concrete command decides on its configuration and runtime state  */
+export class DaemonCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register the CLI sub-command group below the CLI command <parent>,
+        which shows its help on its own (as it requires a sub-command)  */
+    group(parent) {
+        const group = parent
+            .command(this.words.split(" ").at(-1))
+            .description(this.description)
+            .action(() => {
+            group.outputHelp();
+            process.exit(1);
+        });
+        return group;
+    }
+    /*  register the CLI sub-command "log" below the CLI sub-command group <group>, showing the
+        log file (resolved by <logFile> from the options of the sub-command) of the process run
+        in the background, where <setup> adds further options to the sub-command and each shown
+        line is passed through <transform> (e.g. to colorize parts of it)  */
+    registerLog(group, logFile, setup = () => { }, transform) {
+        const cmd = group
+            .command("log")
+            .description(`Show the log of the ${this.label} run in the background`)
+            .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)");
+        setup(cmd);
+        cmd.action(async (opts) => {
+            const file = logFile(opts);
+            if (!fs.existsSync(file)) {
+                this.log.write("info", `${this.label}: no log file "${file}" ` +
+                    "(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);
+        });
+    }
+    /*  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);
+        const fd = fs.openSync(logFile, "a");
+        const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
+        const child = spawn(process.execPath, [entry, ...args], {
+            detached: true,
+            env: { ...process.env, ...env },
+            stdio: ["ignore", fd, fd]
+        });
+        fs.closeSync(fd);
+        return child;
+    }
+    /*  await the readiness of a child process (checked every 100ms up to <timeout> milliseconds),
+        resolving to null once ready, else to the reason of its failure, like "exited during
+        startup (code 1)" (where a child process not ready within the timeout is terminated)  */
+    async awaitChild(child, ready, timeout) {
+        let exited = false;
+        let exitCode = null;
+        child.once("exit", (code) => {
+            exited = true;
+            exitCode = code;
+        });
+        for (let waited = 0; waited < timeout; waited += 100) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            if (exited)
+                break;
+            if (ready())
+                return null;
+        }
+        if (!exited)
+            child.kill("SIGTERM");
+        return exited ?
+            `exited during startup (code ${exitCode})` :
+            "failed to start within timeout";
+    }
+    /*  await the readiness of the detached process, else fail with the tail of its log file  */
+    async awaitDetached(child, logFile, ready, timeout) {
+        const failure = await this.awaitChild(child, ready, timeout);
+        child.unref();
+        if (failure === null)
+            return;
+        const reason = `${this.label}: ${failure}`;
+        const tail = Service.readLogTail(logFile, 20);
+        throw new Error(tail.length > 0 ? `${reason}\n---- ${logFile} (tail) ----\n${tail}` : reason);
+    }
+    /*  check whether a process is still alive  */
+    isAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            return err.code === "EPERM";
+        }
+    }
+    /*  terminate a process and wait (up to <timeout> milliseconds) until it is gone,
+        resolving to false if it was already gone  */
+    async terminate(pid, timeout) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch (err) {
+            const e = err;
+            if (e.code !== "ESRCH")
+                throw err;
+            return false;
+        }
+        for (let waited = 0; waited < timeout; waited += 100) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            if (!this.isAlive(pid))
+                return true;
+        }
+        throw new Error(`${this.label}: process ${pid} did not stop within timeout`);
+    }
+}

package/dst/ase-lib-hash.js

@@ -0,0 +1,20 @@
+/*
+**  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 { createHash } from "node:crypto";
+/*  the alphabet and length of the NanoId-style hashes  */
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const NANOID = 10;
+/*  derive the short NanoId-style hash of a hint: the SHA-1 digest of
+    the hint, base62-encoded and truncated to its lowest digits  */
+export const nanoid = (hint) => {
+    let n = BigInt(`0x${createHash("sha1").update(hint).digest("hex")}`);
+    let id = "";
+    for (let i = 0; i < NANOID; i++) {
+        id += BASE62[Number(n % 62n)];
+        n /= 62n;
+    }
+    return id;
+};