@rse/ase 0.9.46 → 0.9.48

package/dst/ase-artifact.js

@@ -10,7 +10,7 @@ import { isScalar } from "yaml";
 import { z } from "zod";
 import { Config, configSchema } from "./ase-config.js";
 import { Task } from "./ase-task.js";
-import { writeStdout } from "./ase-stdout.js";
+import { writeStdout } from "./ase-stdio.js";
 /*  the recognized artifact kinds, in descending precedence order;
     "othr" is the implicit catch-all and is always resolved last  */
 export const artifactKinds = ["spec", "arch", "code", "docs", "infr", "othr"];
@@ -141,6 +141,8 @@ export class Artifact {
         const basedir = Artifact.configString(cfg, `project.artifact.${kind}.basedir`)
             .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
             .replace(/^\.$/, "");
+        if (basedir.split("/").includes(".."))
+            throw new Error(`artifact: configured "basedir" "${basedir}" must not escape the project root`);
         const files = Artifact.configString(cfg, `project.artifact.${kind}.files`);
         return { basedir, files };
     }

package/dst/ase-compat.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import { writeStdout } from "./ase-stdio.js";
 /*  the canonical expected values for every ase-meta-compat probe,
     keyed by "<category>/<probe-name>" as used in the skill  */
 const EXPECTED = {
@@ -44,8 +45,8 @@ export default class CompatCommand {
         program
             .command("compat")
             .description("Output expected probe values for the ase-meta-compat self-test skill")
-            .action(() => {
-            process.stdout.write(formatExpected());
+            .action(async () => {
+            await writeStdout(formatExpected());
         });
     }
 }

package/dst/ase-config.js

@@ -14,6 +14,8 @@ import Table from "cli-table3";
 import writeFileAtomic from "write-file-atomic";
 import lockfile from "proper-lockfile";
 import { z } from "zod";
+import { LRUCache } from "lru-cache";
+import { writeStdout } from "./ase-stdio.js";
 /*  classification taxonomy  */
 export const projectClassification = {
     boxing: ["white", "grey", "black"]
@@ -92,20 +94,33 @@ const parseScopeTerm = (value) => {
     else if (value === "project")
         return { kind: "project" };
     const m = /^(session|task):([A-Za-z0-9._-]+)$/.exec(value);
-    if (m !== null)
+    if (m !== null) {
+        if (m[2] === "." || m[2] === "..")
+            throw new Error(`invalid --scope term "${value}": id must not be "." or ".."`);
         return { kind: m[1], id: m[2] };
+    }
     throw new Error(`invalid --scope term "${value}" ` +
         "(expected: \"user\", \"project\", \"task:<id>\", or \"session:<id>\")");
 };
-/*  determine the Git top-level directory, if inside a Git repository  */
+/*  determine the Git top-level directory, if inside a Git repository;
+    cached per working directory ("" ≡ not inside a Git working tree), as
+    each determination spawns a Git subprocess and the Git context can
+    change over the lifetime of the long-running ASE service  */
+const gitToplevelCache = new LRUCache({ max: 4, ttl: 2 * 1000 });
 const gitToplevel = () => {
+    const cwd = process.cwd();
+    const cached = gitToplevelCache.get(cwd);
+    if (cached !== undefined)
+        return cached === "" ? null : cached;
+    let top = "";
     try {
-        const result = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" });
-        return result.stdout.trim() || null;
+        top = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" }).stdout.trim();
     }
     catch {
-        return null;
+        /*  not inside a Git working tree  */
     }
+    gitToplevelCache.set(cwd, top);
+    return top === "" ? null : top;
 };
 /*  detect whether a project context exists, i.e. either we are inside
     a Git working tree or a ".ase" directory is present at or above cwd  */
@@ -153,6 +168,11 @@ export const parseScope = (value) => {
     terms.unshift({ kind: "default" });
     return terms;
 };
+/*  schema for a single artifact kind's "basedir"/"files" specification  */
+const artifactSchema = v.optional(v.strictObject({
+    basedir: v.optional(v.string()),
+    files: v.optional(v.string())
+}));
 /*  schema for ".ase/config.yaml"  */
 export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
@@ -160,12 +180,12 @@ export const configSchema = v.nullish(v.strictObject({
         name: v.optional(v.pipe(v.string(), v.minLength(1))),
         boxing: v.optional(v.picklist(projectClassification.boxing)),
         artifact: v.optional(v.strictObject({
-            spec: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
-            arch: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
-            code: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
-            docs: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
-            infr: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
-            task: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) }))
+            spec: artifactSchema,
+            arch: artifactSchema,
+            code: artifactSchema,
+            docs: artifactSchema,
+            infr: artifactSchema,
+            task: artifactSchema
         }))
     })),
     agent: v.optional(v.strictObject({
@@ -188,7 +208,7 @@ export class Config {
     docs;
     target;
     /*  creation  */
-    constructor(name, schema, log, scope = [{ kind: "project" }]) {
+    constructor(name, schema, log, scope = [{ kind: "user" }, { kind: "project" }]) {
         if (scope.length === 0)
             throw new Error("invalid scope: chain must not be empty");
         this.name = name;
@@ -560,7 +580,7 @@ export default class ConfigCommand {
         configCmd
             .command("list")
             .description("list all configured values as flat dotted keys")
-            .action((_opts, cmd) => {
+            .action(async (_opts, cmd) => {
             const scope = parseScope(cmd.optsWithGlobals().scope);
             const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
@@ -573,7 +593,7 @@ export default class ConfigCommand {
                 const val = isScalar(e.value) ? e.value.value : e.value;
                 table.push([e.key, String(val), Config.scopeLabel(e.scope)]);
             }
-            process.stdout.write(`${table.toString()}\n`);
+            await writeStdout(`${table.toString()}\n`);
         });
         /*  register CLI sub-command "ase config edit"  */
         configCmd
@@ -612,7 +632,7 @@ export default class ConfigCommand {
             .command("get")
             .description("print the value at a dotted configuration key")
             .argument("<key>", "configuration key (dotted path)")
-            .action((key, _opts, cmd) => {
+            .action(async (key, _opts, cmd) => {
             const scope = parseScope(cmd.optsWithGlobals().scope);
             const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
@@ -621,7 +641,7 @@ export default class ConfigCommand {
                 throw new Error(`key "${key}" is not set`);
             if (isMap(val))
                 throw new Error(`key "${key}" is not a leaf key`);
-            process.stdout.write(`${isScalar(val) ? val.value : val}\n`);
+            await writeStdout(`${isScalar(val) ? val.value : val}\n`);
         });
         /*  register CLI sub-command "ase config set"  */
         configCmd

package/dst/ase-diagram.js

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import { InvalidArgumentError } from "commander";
 import { renderMermaidASCII, renderMermaidSVG } from "beautiful-mermaid";
 import { z } from "zod";
-import getStdin from "get-stdin";
+import { readStdin } from "./ase-stdio.js";
 /*  custom argument parser for Commander: non-negative integer  */
 const parseInteger = (name) => (value) => {
     const n = Number.parseInt(value, 10);
@@ -150,6 +150,8 @@ export class Diagram {
             clipping below are meaningful only for ASCII art)  */
         if (opts.format === "svg")
             return renderMermaidSVG(src);
+        /*  determine theme colors (gray shades once colors are enabled)  */
+        const colored = opts.colorMode !== "none";
         /*  create diagram rendering  */
         let out = renderMermaidASCII(src, {
             useAscii: opts.ascii,
@@ -157,20 +159,13 @@ export class Diagram {
             paddingY: opts.nodeMarginY,
             boxBorderPadding: opts.nodePadding,
             colorMode: opts.colorMode,
-            theme: opts.colorMode !== "none" ? {
+            theme: {
                 fg: "#000000",
-                border: "#a0a0a0",
-                junction: "#a0a0a0",
-                arrow: "#404040",
-                line: "#707070",
-                corner: "#707070"
-            } : {
-                fg: "#000000",
-                border: "#000000",
-                junction: "#000000",
-                arrow: "#000000",
-                line: "#000000",
-                corner: "#000000"
+                border: colored ? "#a0a0a0" : "#000000",
+                junction: colored ? "#a0a0a0" : "#000000",
+                arrow: colored ? "#404040" : "#000000",
+                line: colored ? "#707070" : "#000000",
+                corner: colored ? "#707070" : "#000000"
             }
         });
         /*  optionally clip diagram rendering  */
@@ -248,7 +243,7 @@ export default class DiagramCommand {
                 }
             }
             else
-                src = await getStdin();
+                src = await readStdin();
             if (src.trim() === "") {
                 this.log.write("error", "diagram: empty Mermaid diagram specification");
                 process.exit(1);

package/dst/ase-getopt.js

@@ -6,6 +6,70 @@
 import { z } from "zod";
 import { Command, Option } from "commander";
 import { parse as shParse, quote as shQuote } from "shell-quote";
+/*  tokenize a raw input string into [start,end) token ranges, preserving
+    the quoting so the original text can later be sliced verbatim  */
+const tokenizeRanges = (input) => {
+    const ranges = [];
+    let i = 0;
+    while (i < input.length) {
+        while (i < input.length && /\s/.test(input[i]))
+            i++;
+        if (i >= input.length)
+            break;
+        const start = i;
+        while (i < input.length && !/\s/.test(input[i])) {
+            const ch = input[i];
+            if (ch === "\"" || ch === "'") {
+                const quote = ch;
+                i++;
+                while (i < input.length && input[i] !== quote) {
+                    if (input[i] === "\\" && i + 1 < input.length)
+                        i++;
+                    i++;
+                }
+                if (i < input.length)
+                    i++;
+            }
+            else
+                i++;
+        }
+        ranges.push({ start, end: i });
+    }
+    return ranges;
+};
+/*  strip surrounding quotes/escapes from a raw token range so it can be
+    compared against an option flag spelling  */
+const unquote = (s) => {
+    let out = "";
+    let j = 0;
+    while (j < s.length) {
+        const ch = s[j];
+        if (ch === "\"" || ch === "'") {
+            const quote = ch;
+            j++;
+            while (j < s.length && s[j] !== quote) {
+                if (s[j] === "\\" && j + 1 < s.length) {
+                    out += s[j + 1];
+                    j += 2;
+                }
+                else {
+                    out += s[j];
+                    j++;
+                }
+            }
+            j++;
+        }
+        else if (ch === "\\" && j + 1 < s.length) {
+            out += s[j + 1];
+            j += 2;
+        }
+        else {
+            out += ch;
+            j++;
+        }
+    }
+    return out;
+};
 /*  MCP registration entry point for the option-parser tool  */
 export class GetoptMCP {
     register(mcp) {
@@ -117,65 +181,7 @@ export class GetoptMCP {
                 let argsVerbatim = "";
                 if (argsRaw !== null) {
                     /*  tokenize raw input into [start,end) ranges, preserving quotes  */
-                    const ranges = [];
-                    let i = 0;
-                    while (i < argsRaw.length) {
-                        while (i < argsRaw.length && /\s/.test(argsRaw[i]))
-                            i++;
-                        if (i >= argsRaw.length)
-                            break;
-                        const start = i;
-                        while (i < argsRaw.length && !/\s/.test(argsRaw[i])) {
-                            const ch = argsRaw[i];
-                            if (ch === "\"" || ch === "'") {
-                                const quote = ch;
-                                i++;
-                                while (i < argsRaw.length && argsRaw[i] !== quote) {
-                                    if (argsRaw[i] === "\\" && i + 1 < argsRaw.length)
-                                        i++;
-                                    i++;
-                                }
-                                if (i < argsRaw.length)
-                                    i++;
-                            }
-                            else
-                                i++;
-                        }
-                        ranges.push({ start, end: i });
-                    }
-                    /*  helper function: strip surrounding quotes/escapes from a raw
-                        range so it can be compared against an option flag spelling  */
-                    const unquote = (s) => {
-                        let out = "";
-                        let j = 0;
-                        while (j < s.length) {
-                            const ch = s[j];
-                            if (ch === "\"" || ch === "'") {
-                                const quote = ch;
-                                j++;
-                                while (j < s.length && s[j] !== quote) {
-                                    if (s[j] === "\\" && j + 1 < s.length) {
-                                        out += s[j + 1];
-                                        j += 2;
-                                    }
-                                    else {
-                                        out += s[j];
-                                        j++;
-                                    }
-                                }
-                                j++;
-                            }
-                            else if (ch === "\\" && j + 1 < s.length) {
-                                out += s[j + 1];
-                                j += 2;
-                            }
-                            else {
-                                out += ch;
-                                j++;
-                            }
-                        }
-                        return out;
-                    };
+                    const ranges = tokenizeRanges(argsRaw);
                     /*  walk the raw ranges, consuming leading option tokens (and any
                         separate value tokens they take) until the first positional
                         is reached, then slice the original input from there -- this
@@ -202,7 +208,7 @@ export class GetoptMCP {
                         argsVerbatim = argsRaw.slice(ranges[idx].start);
                 }
                 else
-                    argsVerbatim = cmd.args.join(" ");
+                    argsVerbatim = shQuote(cmd.args);
                 /*  build markdown info rendering of parsed options  */
                 const opts = cmd.opts();
                 const info = Object.entries(opts)

package/dst/ase-hook.js

@@ -8,11 +8,10 @@ import fs from "node:fs";
 import os from "node:os";
 import { execaSync } from "execa";
 import { quote } from "shell-quote";
-import getStdin from "get-stdin";
 import * as v from "valibot";
 import Version from "./ase-version.js";
 import { Config, configSchema, parseScope } from "./ase-config.js";
-import { writeStdout } from "./ase-stdout.js";
+import { readStdin, writeStdout } from "./ase-stdio.js";
 const addonMcpServers = [
     "chat-alibaba-qwen",
     "chat-deepseek",
@@ -69,6 +68,13 @@ const toolSpecs = {
         approvalEvent: "PermissionRequest"
     }
 };
+/*  schema (and derived type) of the tool invocation input fields
+    inspected by the tool-approval decision logic  */
+const toolInputSchema = v.object({
+    command: v.optional(v.string()),
+    skill: v.optional(v.string()),
+    file_path: v.optional(v.string())
+});
 /*  CLI command "ase hook"  */
 export default class HookCommand {
     log;
@@ -79,14 +85,9 @@ export default class HookCommand {
     isValidSessionId(id) {
         return /^[A-Za-z0-9._-]+$/.test(id);
     }
-    /*  read the entire stdin payload asynchronously  */
-    readStdin() {
-        /*  best-effort: treat an unreadable/closed stdin as empty  */
-        return getStdin().catch(() => "");
-    }
     /*  drain and discard the stdin event payload  */
     async drainStdin() {
-        await this.readStdin();
+        await readStdin().catch(() => "");
     }
     /*  best-effort JSON parse with valibot schema validation: returns
         an empty object on blank input, malformed JSON, or schema
@@ -204,7 +205,7 @@ export default class HookCommand {
         const versionHint = versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
         /*  read session information (Anthropic Claude Code CLI uses snake_case fields,
             GitHub Copilot CLI uses camelCase fields)  */
-        const stdin = await this.readStdin();
+        const stdin = await readStdin().catch(() => "");
         const input = this.parseJSON(stdin, v.object({
             session_id: v.optional(v.string()),
             sessionId: v.optional(v.string()),
@@ -242,16 +243,15 @@ export default class HookCommand {
         const projectId = path.basename(projectDir);
         /*  determine user id  */
         const userId = process.env.USER ?? process.env.LOGNAME ?? "unknown";
-        /*  determine agent persona style  */
-        let persona = process.env.ASE_PERSONA_STYLE ?? "engineer";
-        const val = cfg.get("agent.persona");
-        if (typeof val === "string")
-            persona = val;
-        /*  determine project boxing transparency  */
-        let boxing = process.env.ASE_PROJECT_BOXING ?? "white";
-        const valBoxing = cfg.get("project.boxing");
-        if (typeof valBoxing === "string")
-            boxing = valBoxing;
+        /*  helper function: determine a setting from the configuration,
+            falling back to an environment variable and a default  */
+        const setting = (key, envVar, dflt) => {
+            const val = cfg.get(key);
+            return typeof val === "string" ? val : (process.env[envVar] ?? dflt);
+        };
+        /*  determine agent persona style and project boxing transparency  */
+        const persona = setting("agent.persona", "ASE_PERSONA_STYLE", "engineer");
+        const boxing = setting("project.boxing", "ASE_PROJECT_BOXING", "white");
         /*  determine headless mode  */
         const headless = (process.env.ASE_HEADLESS ?? "false") === "true" ? "true" : "false";
         /*  provide ASE information to Anthropic Claude Code CLI shell commands
@@ -267,7 +267,13 @@ export default class HookCommand {
                 `export ASE_SESSION_ID=${quote([sessionId])}\n` +
                 `export ASE_HEADLESS=${quote([headless])}\n` +
                 `export ASE_AGENT_TOOL=${quote([tool])}\n`;
-            fs.appendFileSync(envFile, script, "utf8");
+            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}`);
+            }
         }
         /*  prepend ASE information to constitution markdown  */
         md =
@@ -365,7 +371,7 @@ export default class HookCommand {
     }
     /*  read session id from stdin JSON payload  */
     async readSessionIdFromStdin() {
-        const stdin = await this.readStdin();
+        const stdin = await readStdin().catch(() => "");
         const input = this.parseJSON(stdin, v.object({
             session_id: v.optional(v.string()),
             sessionId: v.optional(v.string())
@@ -422,13 +428,12 @@ export default class HookCommand {
         let toolInput = {};
         const rawInput = input[spec.toolInputField];
         if (spec.toolInputIsString && typeof rawInput === "string")
-            toolInput = this.parseJSON(rawInput, v.object({
-                command: v.optional(v.string()),
-                skill: v.optional(v.string()),
-                file_path: v.optional(v.string())
-            }));
-        else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null)
-            toolInput = rawInput;
+            toolInput = this.parseJSON(rawInput, toolInputSchema);
+        else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null) {
+            const result = v.safeParse(toolInputSchema, rawInput);
+            if (result.success)
+                toolInput = result.output;
+        }
         const command = toolInput.command ?? "";
         if (toolName === spec.bashToolName && /^ase(\s|$)/.test(command)
             && !/[;&|<>`\n]|\$\(/.test(command))
@@ -453,7 +458,7 @@ export default class HookCommand {
         loosely-typed input object shared by the tool-approval handlers  */
     async readHookInput(tool) {
         const spec = toolSpecs[tool];
-        const stdin = await this.readStdin();
+        const stdin = await readStdin().catch(() => "");
         const input = this.parseJSON(stdin, v.looseObject({
             session_id: v.optional(v.string()),
             sessionId: v.optional(v.string())
@@ -538,53 +543,22 @@ export default class HookCommand {
             hookCmd.outputHelp();
             process.exit(1);
         });
-        /*  register CLI sub-command "ase hook session-start"  */
-        hookCmd
-            .command("session-start")
-            .description("handle SessionStart hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doSessionStart(this.parseTool(opts.tool));
-        });
-        /*  register CLI sub-command "ase hook session-end"  */
-        hookCmd
-            .command("session-end")
-            .description("handle SessionEnd hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doSessionEnd(this.parseTool(opts.tool));
-        });
-        /*  register CLI sub-command "ase hook pre-tool-use"  */
-        hookCmd
-            .command("pre-tool-use")
-            .description("handle tool PreToolUse hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doPreToolUse(this.parseTool(opts.tool));
-        });
-        /*  register CLI sub-command "ase hook permission-request"  */
-        hookCmd
-            .command("permission-request")
-            .description("handle tool PermissionRequest hook event (Codex CLI)")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doPermissionRequest(this.parseTool(opts.tool));
-        });
-        /*  register CLI sub-command "ase hook user-prompt-submit"  */
-        hookCmd
-            .command("user-prompt-submit")
-            .description("handle UserPromptSubmit hook event (mark agent as busy)")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doUserPromptSubmit(this.parseTool(opts.tool));
-        });
-        /*  register CLI sub-command "ase hook stop"  */
-        hookCmd
-            .command("stop")
-            .description("handle Stop hook event (mark agent as ready)")
-            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
-            .action(async (opts) => {
-            process.exitCode = await this.doStop(this.parseTool(opts.tool));
-        });
+        /*  register CLI sub-commands "ase hook <event>"  */
+        const subCmds = [
+            { name: "session-start", desc: "handle SessionStart hook event", handler: (tool) => this.doSessionStart(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) },
+            { name: "user-prompt-submit", desc: "handle UserPromptSubmit hook event", handler: (tool) => this.doUserPromptSubmit(tool) },
+            { name: "stop", desc: "handle Stop hook event", handler: (tool) => this.doStop(tool) }
+        ];
+        for (const { name, desc, handler } of subCmds)
+            hookCmd
+                .command(name)
+                .description(desc)
+                .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+                .action(async (opts) => {
+                process.exitCode = await handler(this.parseTool(opts.tool));
+            });
     }
 }