@rse/ase 1.0.7 → 2.0.1

package/dst/{ase-compat.js → ase-util-compat.js}

@@ -3,7 +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";
+import { writeStdout } from "./ase-lib-stdio.js";
 /*  the canonical expected values for every ase-meta-compat probe,
     keyed by "<category>/<probe-name>" as used in the skill  */
 const EXPECTED = {
@@ -39,7 +39,7 @@ const EXPECTED = {
 };
 /*  format the expected values as "<id>: <value>\n" lines  */
 const formatExpected = () => Object.entries(EXPECTED).map(([id, value]) => `${id}: ${value}`).join("\n") + "\n";
-/*  CLI command "ase compat"  */
+/*  CLI command "ase util compat"  */
 export default class CompatCommand {
     register(program) {
         program

package/dst/{ase-diagram.js → ase-util-diagram.js}

@@ -5,9 +5,8 @@
 */
 import fs from "node:fs";
 import { InvalidArgumentError } from "commander";
-import { renderMermaidASCII, renderMermaidSVG } from "beautiful-mermaid";
 import { z } from "zod";
-import { readStdin } from "./ase-stdio.js";
+import { readStdin } from "./ase-lib-stdio.js";
 /*  custom argument parser for Commander: non-negative integer  */
 const parseInteger = (name) => (value) => {
     const n = Number.parseInt(value, 10);
@@ -21,12 +20,34 @@ const parseColorMode = (name) => (value) => {
         throw new InvalidArgumentError(`${name} must be "none", "ansi16", or "ansi256"`);
     return value;
 };
+/*  custom argument parser for Commander: diagram language  */
+const parseLang = (name) => (value) => {
+    if (value !== "mermaid" && value !== "d2")
+        throw new InvalidArgumentError(`${name} must be "mermaid" or "d2"`);
+    return value;
+};
 /*  custom argument parser for Commander: output format  */
 const parseFormat = (name) => (value) => {
     if (value !== "ascii" && value !== "svg")
         throw new InvalidArgumentError(`${name} must be "ascii" or "svg"`);
     return value;
 };
+/*  the D2 compiler, created on first use only (as it spins up the
+    WebAssembly build of D2 in a worker thread, which keeps the process
+    alive until the compiler is disposed)  */
+let d2 = null;
+/*  turn a D2 compile failure (a JSON-encoded list of errors) into a message  */
+const d2Error = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+        return JSON.parse(message)
+            .map((error) => error.errmsg.replace(/^index:/, "line "))
+            .join("; ");
+    }
+    catch {
+        return message;
+    }
+};
 /*  scan a CSI escape sequence starting at line[i] (where line[i]===ESC and
     line[i+1]==="["); return the index just past the terminating letter, or
     -1 if the sequence is unterminated within the line  */
@@ -141,19 +162,48 @@ export class Diagram {
         }
         return mode;
     }
-    /*  pure rendering helper: turn a Mermaid source string plus options into
-        a rendered Unicode/ASCII diagram string, or an SVG document string
-        when "svg" format is requested. Throws on render failure.  */
-    static render(src, opts) {
+    /*  dispose the D2 compiler (if any), so its worker thread no longer
+        keeps the process alive (used by the short-lived CLI only)  */
+    static async dispose() {
+        if (d2 === null)
+            return;
+        const compiler = d2;
+        d2 = null;
+        await (await compiler).dispose();
+    }
+    /*  render a D2 source string as Unicode/ASCII art or SVG document
+        ("@d2lang/d2" is loaded on first use only; the ANSI "colorMode"
+        and the node margins/padding are not supported by D2)  */
+    static async renderD2(src, opts) {
+        d2 ??= import("@d2lang/d2").then((module) => new module.D2()).catch((err) => {
+            d2 = null;
+            throw err;
+        });
+        const compiler = await d2;
+        try {
+            const result = await compiler.compile(src);
+            return await compiler.render(result.diagram, {
+                ...result.renderOptions,
+                ascii: opts.format === "ascii",
+                asciiMode: opts.ascii ? "standard" : "extended"
+            });
+        }
+        catch (err) {
+            throw new Error(d2Error(err), { cause: err });
+        }
+    }
+    /*  render a Mermaid source string as Unicode/ASCII art or SVG document
+        ("beautiful-mermaid" is loaded on first use only)  */
+    static async renderMermaid(src, opts) {
+        const { renderMermaidASCII, renderMermaidSVG } = await import("beautiful-mermaid");
         /*  render as a self-contained SVG document using the library's
-            themed defaults (the ANSI "colorMode" and the terminal
-            clipping below are meaningful only for ASCII art)  */
+            themed defaults (the ANSI "colorMode" is 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, {
+        return renderMermaidASCII(src, {
             useAscii: opts.ascii,
             paddingX: opts.nodeMarginX,
             paddingY: opts.nodeMarginY,
@@ -168,6 +218,24 @@ export class Diagram {
                 corner: colored ? "#707070" : "#000000"
             }
         });
+    }
+    /*  pure rendering helper: turn a Mermaid or D2 source string plus
+        options into a rendered Unicode/ASCII diagram string, or an SVG
+        document string when "svg" format is requested. Throws on render
+        failure. (the terminal clipping is meaningful only for ASCII art)  */
+    static async render(src, opts) {
+        /*  create diagram rendering  */
+        let out = opts.lang === "d2" ?
+            await Diagram.renderD2(src, opts) :
+            await Diagram.renderMermaid(src, opts);
+        if (opts.format === "svg")
+            return out;
+        /*  determine language-specific regeneration hints  */
+        const lang = opts.lang === "d2" ? "D2" : "Mermaid";
+        const portrait = opts.lang === "d2" ?
+            "(\"direction: down\", top-to-bottom) over landscape (\"direction: right\"/\"left\"/\"up\")" :
+            "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\")";
+        const nesting = opts.lang === "d2" ? "nested container" : "nested subgraph";
         /*  optionally clip diagram rendering  */
         const termWidth = opts.terminalWidth;
         const termHeight = opts.terminalHeight;
@@ -182,19 +250,19 @@ export class Diagram {
                 const widest = lines.reduce((m, l) => Math.max(m, visibleWidth(l)), 0);
                 if (widest > maxWidth)
                     widthWarn =
-                        `ase diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
-                            "rightmost content was clipped. Please regenerate the Mermaid source to fit " +
+                        `ase util diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
+                            `rightmost content was clipped. Please regenerate the ${lang} source to fit ` +
                             `within ${maxWidth} chars by preferring a portrait orientation ` +
-                            "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\"), " +
+                            `${portrait}, ` +
                             "reducing siblings per row, abbreviating node labels, or restructuring " +
-                            "into nested subgraph hierarchies.";
+                            `into ${nesting} hierarchies.`;
                 lines = lines.map((l) => truncateAnsiLine(l, maxWidth));
             }
             if (maxHeight > 0 && lines.length > maxHeight) {
                 const overflow = lines.length - maxHeight;
                 heightWarn =
-                    `ase diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
-                        `bottom ${overflow} line(s) were clipped. Please regenerate the Mermaid source to fit ` +
+                    `ase util diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
+                        `bottom ${overflow} line(s) were clipped. Please regenerate the ${lang} source to fit ` +
                         `within ${maxHeight} lines by reducing depth or splitting into multiple diagrams.`;
                 lines = lines.slice(0, maxHeight);
             }
@@ -217,20 +285,21 @@ export default class DiagramCommand {
     register(program) {
         program
             .command("diagram")
-            .description("Render Mermaid diagram specification as Unicode/ASCII art or SVG")
-            .option("-i, --input <file>", "read Mermaid source from file instead of stdin")
+            .description("Render Mermaid or D2 diagram specification as Unicode/ASCII art or SVG")
+            .option("-i, --input <file>", "read diagram source from file instead of stdin")
+            .option("-l, --lang <lang>", "diagram language (\"mermaid\" or \"d2\")", parseLang("--lang"), "mermaid")
             .option("-f, --format <format>", "output format (\"ascii\" or \"svg\")", parseFormat("--format"), "ascii")
             .option("-a, --ascii", "emit plain ASCII (+-|) instead of Unicode box-drawing", false)
-            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\")", parseColorMode("--color-mode"), Diagram.detectColorMode())
-            .option("--node-margin-x <n>", "horizontal margin between nodes of <n> characters", parseInteger("--node-margin-x"), 3)
-            .option("--node-margin-y <n>", "vertical margin between nodes of <n> lines", parseInteger("--node-margin-y"), 3)
-            .option("--node-padding <n>", "horizontal and vertical inner node padding with <n> characters", parseInteger("--node-padding"), 1)
+            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\") (Mermaid only)", parseColorMode("--color-mode"), Diagram.detectColorMode())
+            .option("--node-margin-x <n>", "horizontal margin between nodes of <n> characters (Mermaid only)", parseInteger("--node-margin-x"), 3)
+            .option("--node-margin-y <n>", "vertical margin between nodes of <n> lines (Mermaid only)", parseInteger("--node-margin-y"), 3)
+            .option("--node-padding <n>", "horizontal and vertical inner node padding with <n> characters (Mermaid only)", parseInteger("--node-padding"), 1)
             .option("--diagram-clip-x <n>", "extra horizontal clipping of diagram to terminal width minus <n> characters", parseInteger("--diagram-clip-x"), 0)
             .option("--diagram-clip-y <n>", "extra vertical clipping of diagram to terminal height minus <n> lines", parseInteger("--diagram-clip-y"), 0)
             .option("--terminal-width <n>", "width of terminal of <n> characters (for diagram clipping)", parseInteger("--terminal-width"), Diagram.detectTermWidth())
             .option("--terminal-height <n>", "height of terminal of <n> lines (for diagram clipping)", parseInteger("--terminal-height"), Diagram.detectTermHeight())
             .action(async (opts) => {
-            /*  fetch Mermaid diagram specification from file or stdin  */
+            /*  fetch diagram specification from file or stdin  */
             let src;
             if (opts.input !== undefined) {
                 try {
@@ -245,19 +314,22 @@ export default class DiagramCommand {
             else
                 src = await readStdin();
             if (src.trim() === "") {
-                this.log.write("error", "diagram: empty Mermaid diagram specification");
+                this.log.write("error", "diagram: empty diagram specification");
                 process.exit(1);
             }
             /*  create diagram rendering  */
             let out;
             try {
-                out = Diagram.render(src, opts);
+                out = await Diagram.render(src, opts);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 this.log.write("error", `diagram: render failed: ${message}`);
                 process.exit(1);
             }
+            finally {
+                await Diagram.dispose();
+            }
             /*  output diagram rendering  */
             process.stdout.write(out);
             if (!out.endsWith("\n"))
@@ -270,7 +342,7 @@ export class DiagramMCP {
     register(mcp) {
         mcp.registerTool("ase_diagram", {
             title: "ASE diagram render",
-            description: "Render a Mermaid diagram as Unicode/ASCII art or SVG. " +
+            description: "Render a Mermaid or D2 diagram as Unicode/ASCII art or SVG. " +
                 "Use for visualizing " +
                 "structure/layout/components/dependencies as a Flowchart, " +
                 "control-flow/branching/concurrency as a Flowchart, " +
@@ -279,23 +351,26 @@ export class DiagramMCP {
                 "data-structure/classes/methods as a UML Class Diagram, " +
                 "data-model/entities/relationships as an ER Diagram, or " +
                 "metrics/distributions/time-series as an XY-Chart. " +
-                "Pass the Mermaid diagram specification as `diagram`. " +
+                "Pass the diagram specification as `diagram` and its language as `lang` " +
+                "(\"mermaid\" by default, or \"d2\"). " +
                 "Returns the rendered art (or SVG document, for `format` \"svg\") as `text`.",
             inputSchema: {
                 diagram: z.string()
-                    .describe("Mermaid diagram specification"),
+                    .describe("Mermaid or D2 diagram specification"),
+                lang: z.enum(["mermaid", "d2"]).default("mermaid")
+                    .describe("diagram language: \"mermaid\" for Mermaid, \"d2\" for D2"),
                 format: z.enum(["ascii", "svg"]).default("ascii")
                     .describe("output format: \"ascii\" for Unicode/ASCII art, \"svg\" for an SVG document"),
                 ascii: z.boolean().default(false)
                     .describe("emit plain ASCII (+-|) instead of Unicode box-drawing characters"),
                 colorMode: z.enum(["none", "ansi16", "ansi256"]).default("none")
-                    .describe("color mode for ANSI escape sequences in the rendered output"),
+                    .describe("color mode for ANSI escape sequences in the rendered output (Mermaid only)"),
                 nodeMarginX: z.number().int().min(0).default(3)
-                    .describe("horizontal margin between nodes, in characters"),
+                    .describe("horizontal margin between nodes, in characters (Mermaid only)"),
                 nodeMarginY: z.number().int().min(0).default(3)
-                    .describe("vertical margin between nodes, in lines"),
+                    .describe("vertical margin between nodes, in lines (Mermaid only)"),
                 nodePadding: z.number().int().min(0).default(1)
-                    .describe("inner horizontal and vertical padding within each node, in characters"),
+                    .describe("inner horizontal and vertical padding within each node, in characters (Mermaid only)"),
                 diagramClipX: z.number().int().min(0).default(0)
                     .describe("extra horizontal clipping: subtract this many characters from `terminalWidth`"),
                 diagramClipY: z.number().int().min(0).default(0)
@@ -307,7 +382,7 @@ export class DiagramMCP {
             }
         }, async (args) => {
             try {
-                const out = Diagram.render(args.diagram, args);
+                const out = await Diagram.render(args.diagram, args);
                 return {
                     content: [{ type: "text", text: out }]
                 };

package/dst/{ase-meta.js → ase-util-meta.js}

@@ -6,7 +6,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-import { writeStdout } from "./ase-stdio.js";
+import { writeStdout } from "./ase-lib-stdio.js";
 /*  reusable functionality: resolve and read plugin "meta/" files  */
 export class Meta {
     /*  determine the plugin "meta/" directory; the build process copies
@@ -45,7 +45,7 @@ export class Meta {
         }
     }
 }
-/*  CLI command "ase meta"  */
+/*  CLI command "ase util meta"  */
 export default class MetaCommand {
     log;
     constructor(log) {

package/dst/{ase-metric.js → ase-util-metric.js}

@@ -5,7 +5,7 @@
 */
 import fs from "node:fs";
 import { z } from "zod";
-import { writeStdout } from "./ase-stdio.js";
+import { writeStdout } from "./ase-lib-stdio.js";
 /*  measure the metrics of the text "content", where "words" are the
     whitespace-separated tokens, "lines" count a trailing line without a
     final newline as a full line, "chars" are Unicode characters (code
@@ -42,7 +42,7 @@ export const measureInput = (file, text) => {
     else
         throw new Error("metric: either \"file\" or \"text\" has to be given");
 };
-/*  CLI command "ase metric"  */
+/*  CLI command "ase util metric"  */
 export default class MetricCommand {
     /*  register commands  */
     register(program) {

package/dst/{ase-mint.js → ase-util-mint.js}

@@ -7,21 +7,22 @@ import { createHash } from "node:crypto";
 import { Option } from "commander";
 import { z } from "zod";
 import UUID from "pure-uuid";
-import { writeStdout } from "./ase-stdio.js";
+import { writeStdout } from "./ase-lib-stdio.js";
+import { nanoid } from "./ase-lib-hash.js";
 /*  the fixed ASE namespace UUID, itself a UUID V5 over the ASE home URL
     within the standard URL namespace, so that all hint-derived UUIDs
     stay stable over time and disjoint from those of other applications  */
 const NAMESPACE = new UUID(5, "ns:URL", "https://ase.tools").format("std");
 /*  mint "count" identifiers of "type" out of "hint": an empty hint
     yields "count" random UUIDs (V4), while a non-empty hint yields
-    exactly one deterministic hash (UUID V5, SHA-1), as hashing is a
+    exactly one deterministic hash (UUID V5, SHA-1, NanoId), as hashing is a
     pure function of the hint and hence cannot produce distinct results
     for it -- a larger count is clamped and reported back as a warning  */
 export const mint = (type, hint, count) => {
     if (!Number.isInteger(count) || count < 1)
         throw new Error("mint: count has to be a positive integer");
-    if (type === "sha1" && hint === "")
-        throw new Error("mint: type \"sha1\" requires a non-empty hint");
+    if (type !== "uuid" && hint === "")
+        throw new Error(`mint: type "${type}" requires a non-empty hint`);
     let warning = "";
     if (hint !== "" && count > 1) {
         warning = `WARNING: type "${type}" is deterministic for a non-empty hint, ` +
@@ -34,27 +35,29 @@ export const mint = (type, hint, count) => {
             ids.push(hint === "" ?
                 new UUID(4).format("std") :
                 new UUID(5, NAMESPACE, hint).format("std"));
-        else
+        else if (type === "sha1")
             ids.push(createHash("sha1").update(hint).digest("hex"));
+        else
+            ids.push(nanoid(hint));
     }
     return { ids, warning };
 };
-/*  CLI command "ase mint"  */
+/*  CLI command "ase util mint"  */
 export default class MintCommand {
     /*  register commands  */
     register(program) {
         program
             .command("mint")
-            .description("Mint hash-derived identifiers (UUID, SHA-1) out of a hint")
+            .description("Mint hash-derived identifiers (UUID, SHA-1, NanoId) out of a hint")
             .addOption(new Option("-t, --type <type>", "identifier type")
-            .choices(["uuid", "sha1"]).default("uuid"))
+            .choices(["uuid", "sha1", "nanoid"]).default("uuid"))
             .option("-c, --count <count>", "number of identifiers to mint (empty hint only)", "1")
             .argument("[hint...]", "hint the identifiers are derived from")
             .action(async (hint, opts) => {
             const count = Number(opts.count);
             const result = mint(opts.type, hint.join(" "), count);
             if (result.warning !== "")
-                process.stderr.write(`ase mint: ${result.warning}\n`);
+                process.stderr.write(`ase util mint: ${result.warning}\n`);
             await writeStdout(`${result.ids.join("\n")}\n`);
         });
     }
@@ -69,15 +72,19 @@ export class MintMCP {
                 "is derived from the hint, or a random UUID V4 if the hint is empty. " +
                 "For `type` `sha1`, the 40-character hexadecimal SHA-1 digest of the hint " +
                 "is derived, which requires a non-empty hint. " +
+                "For `type` `nanoid`, a 10-character, NanoId-style base62 hash of the hint " +
+                "(the SHA-1 digest, base62-encoded and truncated) is derived, which requires " +
+                "a non-empty hint, too. " +
                 "Pass `count` to mint more than one random UUID V4 at once, which is " +
                 "possible for an empty hint only, as hashing a non-empty hint is " +
                 "deterministic and hence always yields exactly one identifier. " +
                 "Returns the minted identifiers as `text`, one per line, optionally " +
                 "preceded by a line starting with `WARNING:`.",
             inputSchema: {
-                type: z.enum(["uuid", "sha1"]).default("uuid")
-                    .describe("identifier type: `uuid` (UUID V5, or V4 for an empty hint) or " +
-                    "`sha1` (SHA-1 hexadecimal digest), default `uuid`"),
+                type: z.enum(["uuid", "sha1", "nanoid"]).default("uuid")
+                    .describe("identifier type: `uuid` (UUID V5, or V4 for an empty hint), " +
+                    "`sha1` (SHA-1 hexadecimal digest), or `nanoid` (NanoId-style base62 hash), " +
+                    "default `uuid`"),
                 hint: z.string().default("")
                     .describe("free-text hint the identifiers are derived from " +
                     "(an empty hint is allowed for `uuid` only)"),

package/dst/{ase-worktree.js → ase-util-worktree.js}

@@ -7,10 +7,13 @@ import path from "node:path";
 import fs from "node:fs";
 import { execaSync } from "execa";
 import { z } from "zod";
-import { writeStdout } from "./ase-stdio.js";
+import { writeStdout } from "./ase-lib-stdio.js";
 /*  the repository-root-relative path components of the base directory
     which holds all ASE-managed Git worktrees  */
 const baseComponents = [".ase", "worktree"];
+/*  the extra path component of the base directory holding the temporary
+    worktrees: as ids never contain ".", it is disjoint from all regular ids  */
+const tempComponent = ".temp";
 /*  reusable functionality: safe resolution of the ASE worktree
     directories under <repo-root>/.ase/worktree/<id>  */
 export class Worktree {
@@ -23,12 +26,12 @@ export class Worktree {
             throw new Error("worktree: id must match [A-Za-z0-9_-]+");
     }
     /*  determine the fully resolved top-level directory of the Git
-        working tree, as a Git worktree can only be created from
-        inside one  */
-    static repoRoot() {
+        working tree of a directory, as a Git worktree can only be
+        created from inside one  */
+    static repoRoot(cwd = process.cwd()) {
         let top = "";
         try {
-            top = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" }).stdout.trim();
+            top = execaSync("git", ["rev-parse", "--show-toplevel"], { cwd, stderr: "ignore" }).stdout.trim();
         }
         catch {
             /*  not inside a Git working tree  */
@@ -64,9 +67,9 @@ export class Worktree {
     /*  resolve the base directory holding all ASE worktrees, asserting
         that every path component below the repository root is a real
         directory; the base directory is created on demand only  */
-    static baseDir(create = false) {
-        let dir = Worktree.repoRoot();
-        for (const component of baseComponents) {
+    static baseDir(create = false, temp = false, cwd = process.cwd()) {
+        let dir = Worktree.repoRoot(cwd);
+        for (const component of temp ? [...baseComponents, tempComponent] : baseComponents) {
             dir = path.join(dir, component);
             Worktree.assertRealDir(dir);
         }
@@ -79,18 +82,18 @@ export class Worktree {
     /*  resolve the worktree directory of a single id; the leaf itself is
         created by "git worktree add" and hence only has to be free of an
         aliasing entry left behind by an earlier run  */
-    static dir(id, create = false) {
+    static dir(id, create = false, temp = false, cwd = process.cwd()) {
         Worktree.validateId(id);
-        const dir = path.join(Worktree.baseDir(create), id);
+        const dir = path.join(Worktree.baseDir(create, temp, cwd), id);
         Worktree.assertRealDir(dir);
         return dir;
     }
 }
-/*  CLI command "ase worktree"  */
+/*  CLI command "ase util worktree"  */
 export default class WorktreeCommand {
     /*  register commands  */
     register(program) {
-        /*  register CLI top-level command "ase worktree"  */
+        /*  register CLI sub-command "ase util worktree"  */
         const worktree = program
             .command("worktree")
             .description("Safely resolve the ASE worktree directories under <repo-root>/.ase/worktree")
@@ -98,22 +101,24 @@ export default class WorktreeCommand {
             worktree.outputHelp();
             process.exit(1);
         });
-        /*  register CLI sub-command "ase worktree base"  */
+        /*  register CLI sub-sub-command "ase util worktree base"  */
         worktree
             .command("base")
             .description("Print the validated base directory holding all ASE worktrees")
             .option("-c, --create", "create the base directory if it does not exist yet")
+            .option("-t, --temp", "use the base directory of the temporary worktrees")
             .action(async (opts) => {
-            await writeStdout(`${Worktree.baseDir(opts.create ?? false)}\n`);
+            await writeStdout(`${Worktree.baseDir(opts.create ?? false, opts.temp ?? false)}\n`);
         });
-        /*  register CLI sub-command "ase worktree path"  */
+        /*  register CLI sub-sub-command "ase util worktree path"  */
         worktree
             .command("path")
             .description("Print the validated worktree directory of a single <id>")
             .argument("<id>", "Worktree identifier")
             .option("-c, --create", "create the base directory if it does not exist yet")
+            .option("-t, --temp", "resolve the id below the base directory of the temporary worktrees")
             .action(async (id, opts) => {
-            await writeStdout(`${Worktree.dir(id, opts.create ?? false)}\n`);
+            await writeStdout(`${Worktree.dir(id, opts.create ?? false, opts.temp ?? false)}\n`);
         });
     }
 }
@@ -135,6 +140,9 @@ export class WorktreeMCP {
                 "link, through a non-directory, or out of the repository, which `git worktree " +
                 "add` would otherwise silently follow and thereby write outside the repository. " +
                 "Set `create` to `true` to also create the base directory. " +
+                "Set `temp` to `true` for a *temporary* worktree, which is a worktree the caller " +
+                "may remove forcibly: it is then resolved below `<repo-root>/.ase/worktree/.temp` " +
+                "instead, a namespace disjoint from all regular worktrees. " +
                 "Fails with an error if the path is unsafe or the current directory is not a " +
                 "Git working tree; in that case you MUST NOT create the worktree at all.",
             inputSchema: {
@@ -142,14 +150,17 @@ export class WorktreeMCP {
                     .describe("worktree identifier (allowed characters: A-Z, a-z, 0-9, '_', '-'); " +
                     "if omitted, the base directory holding all ASE worktrees is returned"),
                 create: z.boolean().optional()
-                    .describe("if true, create the base directory if it does not exist yet (default: false)")
+                    .describe("if true, create the base directory if it does not exist yet (default: false)"),
+                temp: z.boolean().optional()
+                    .describe("if true, resolve below the base directory of the temporary worktrees (default: false)")
             }
         }, async (args) => {
             try {
                 const create = args.create ?? false;
+                const temp = args.temp ?? false;
                 const text = args.id !== undefined ?
-                    Worktree.dir(args.id, create) :
-                    Worktree.baseDir(create);
+                    Worktree.dir(args.id, create, temp) :
+                    Worktree.baseDir(create, temp);
                 return {
                     content: [{ type: "text", text }]
                 };

package/dst/ase-util.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>
+*/
+/*  CLI command "ase util"  */
+export default class UtilCommand {
+    /*  register command  */
+    register(program) {
+        /*  register CLI top-level command "ase util"  */
+        const util = program
+            .command("util")
+            .description("Utility commands (meta, compat, diagram, worktree, mint, metric)")
+            .action(() => {
+            util.outputHelp();
+            process.exit(1);
+        });
+        return util;
+    }
+}