@rse/ase 0.9.5 → 0.9.7

package/dst/ase-artifact.js

@@ -0,0 +1,331 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import picomatch from "picomatch";
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema } from "./ase-config.js";
+import { Task } from "./ase-task.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"];
+/*  the five configured kinds (i.e. all kinds except the implicit "othr")  */
+const configuredKinds = ["spec", "arch", "code", "docs", "infr"];
+/*  reusable functionality: resolve artifact kinds to project-relative
+    file lists, driven by the "project.artifact.<kind>" configuration  */
+export class Artifact {
+    /*  validate a requested kind against the known set  */
+    static validateKind(kind) {
+        if (!artifactKinds.includes(kind))
+            throw new Error(`artifact: unknown kind "${kind}" ` +
+                `(expected one of: ${artifactKinds.join(", ")})`);
+        return kind;
+    }
+    /*  translate a single ".gitignore" line into a picomatch-backed rule,
+        honoring the anchored-vs-floating, directory-only, and negation
+        semantics of ".gitignore" patterns  */
+    static compileIgnoreRule(line) {
+        let pattern = line.trim();
+        if (pattern === "" || pattern.startsWith("#"))
+            return null;
+        let negated = false;
+        if (pattern.startsWith("!")) {
+            negated = true;
+            pattern = pattern.slice(1);
+        }
+        let dirOnly = false;
+        if (pattern.endsWith("/")) {
+            dirOnly = true;
+            pattern = pattern.slice(0, -1);
+        }
+        const anchored = pattern.includes("/");
+        if (pattern.startsWith("/"))
+            pattern = pattern.slice(1);
+        const glob = anchored ? pattern : `**/${pattern}`;
+        const isMatch = picomatch(glob, { dot: true });
+        return { matcher: (p) => isMatch(p), negated, dirOnly };
+    }
+    /*  load the ".gitignore" rules located directly in a directory  */
+    static loadIgnoreRules(dir) {
+        const file = path.join(dir, ".gitignore");
+        if (!fs.existsSync(file))
+            return [];
+        const rules = [];
+        for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+            const rule = Artifact.compileIgnoreRule(line);
+            if (rule !== null)
+                rules.push(rule);
+        }
+        return rules;
+    }
+    /*  decide whether a project-relative path is ignored by the given
+        ordered ".gitignore" rule set (last matching rule wins)  */
+    static isIgnored(rel, isDir, rules) {
+        let ignored = false;
+        for (const rule of rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.matcher(rel))
+                ignored = !rule.negated;
+        }
+        return ignored;
+    }
+    /*  build the file universe by walking the project tree from the
+        project root, honoring ".gitignore" rules (root plus nested) and
+        always pruning ".git". Yields POSIX project-relative, sorted,
+        de-duplicated file paths  */
+    static universe() {
+        const root = Task.projectRoot();
+        const files = new Set();
+        const walk = (dir, relDir, inherited) => {
+            const rules = [...inherited, ...Artifact.loadIgnoreRules(dir)];
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.name === ".git")
+                    continue;
+                const rel = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+                const isDir = entry.isDirectory();
+                if (Artifact.isIgnored(rel, isDir, rules))
+                    continue;
+                if (isDir)
+                    walk(path.join(dir, entry.name), rel, rules);
+                else if (entry.isFile())
+                    files.add(rel);
+            }
+        };
+        walk(root, "", []);
+        return [...files].sort((a, b) => a.localeCompare(b));
+    }
+    /*  raw-resolve a single kind's configuration spec against the file
+        universe via "seed-then-mutate" miniglob semantics: the spec is a
+        whitespace-separated list of tokens.  */
+    static rawResolve(spec, all) {
+        const tokens = spec.split(/\s+/).filter((t) => t !== "");
+        if (tokens.length === 0)
+            return new Set();
+        const result = new Set(tokens[0].startsWith("!") ? all : []);
+        for (const token of tokens) {
+            const negated = token.startsWith("!");
+            const glob = negated ? token.slice(1) : token;
+            if (glob === "")
+                continue;
+            const isMatch = picomatch(glob, { dot: true });
+            for (const file of all) {
+                if (!isMatch(file))
+                    continue;
+                if (negated)
+                    result.delete(file);
+                else
+                    result.add(file);
+            }
+        }
+        return result;
+    }
+    /*  read a single scalar configuration value as a plain string  */
+    static configString(cfg, key) {
+        const val = cfg.get(key);
+        if (val === undefined)
+            return "";
+        return String(isScalar(val) ? val.value : val);
+    }
+    /*  read the configured "basedir" anchor and "files" miniglob spec
+        for a single kind; "basedir" is project-root-relative (POSIX,
+        "" ≡ project root) and "files" resolves relative to "basedir"  */
+    static spec(log, kind) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const basedir = Artifact.configString(cfg, `project.artifact.${kind}.basedir`)
+            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
+            .replace(/^\.$/, "");
+        const files = Artifact.configString(cfg, `project.artifact.${kind}.files`);
+        return { basedir, files };
+    }
+    /*  raw-resolve a single kind's "basedir"/"files" spec against the
+        file universe: the "files" miniglob resolves relative to
+        "basedir", then matches are re-prefixed with "basedir" to stay
+        project-relative  */
+    static resolveKind(basedir, files, all) {
+        if (basedir === "")
+            return Artifact.rawResolve(files, all);
+        const prefix = `${basedir}/`;
+        const local = all
+            .filter((file) => file.startsWith(prefix))
+            .map((file) => file.slice(prefix.length));
+        const result = new Set();
+        for (const file of Artifact.rawResolve(files, local))
+            result.add(`${prefix}${file}`);
+        return result;
+    }
+    /*  resolve the requested kinds to project-relative file lists  */
+    static list(log, kinds) {
+        const all = Artifact.universe();
+        /*  raw-resolve all five configured kinds  */
+        const raw = new Map();
+        for (const kind of configuredKinds) {
+            const { basedir, files } = Artifact.spec(log, kind);
+            raw.set(kind, Artifact.resolveKind(basedir, files, all));
+        }
+        /*  partition the universe by descending precedence  */
+        const claimed = new Set();
+        const part = new Map();
+        for (const kind of configuredKinds) {
+            const own = [];
+            for (const file of raw.get(kind).size > 0 ? all : []) {
+                if (raw.get(kind).has(file) && !claimed.has(file)) {
+                    own.push(file);
+                    claimed.add(file);
+                }
+            }
+            part.set(kind, own);
+        }
+        part.set("othr", all.filter((file) => !claimed.has(file)));
+        /*  project onto the requested kinds  */
+        return kinds.map((kind) => ({
+            kind,
+            files: part.get(kind) ?? []
+        }));
+    }
+    /*  resolve a base-relative "filename" within a kind's "basedir" to a
+        project-root-relative POSIX path; the implicit "othr" catch-all
+        has no configured "basedir" and is therefore rejected  */
+    static name(log, kind, filename) {
+        if (kind === "othr")
+            throw new Error("artifact: kind \"othr\" has no configured basedir");
+        const file = filename.replace(/\\/g, "/").replace(/^\/+/, "");
+        if (file === "")
+            throw new Error("artifact: filename must not be empty");
+        const { basedir } = Artifact.spec(log, kind);
+        return basedir === "" ? file : `${basedir}/${file}`;
+    }
+}
+/*  CLI command "ase artifact"  */
+export default class ArtifactCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase artifact"  */
+        const artifact = program
+            .command("artifact")
+            .description("Resolve project artifact kinds to project-relative file lists")
+            .action(() => {
+            artifact.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase artifact list"  */
+        artifact
+            .command("list")
+            .description("Resolve one or more artifact kinds to project-relative file paths")
+            .option("--kind <kinds>", "comma-separated list of artifact kinds " +
+            `(${artifactKinds.join("|")})`, artifactKinds.join(","))
+            .action((opts) => {
+            const kinds = opts.kind.split(",").map((k) => Artifact.validateKind(k.trim()));
+            const result = Artifact.list(this.log, kinds);
+            const single = result.length === 1;
+            for (const { kind, files } of result) {
+                if (!single)
+                    process.stdout.write(`# ${kind}:\n`);
+                for (const file of files)
+                    process.stdout.write(`- ${file}\n`);
+            }
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase artifact name"  */
+        artifact
+            .command("name")
+            .description("Resolve a base-relative filename within an artifact kind to a project-relative path")
+            .argument("<filename>", "base-relative filename within the kind's basedir")
+            .option("--kind <kind>", "artifact kind " +
+            `(${configuredKinds.join("|")})`, "code")
+            .action((filename, opts) => {
+            const kind = Artifact.validateKind(opts.kind.trim());
+            process.stdout.write(`${Artifact.name(this.log, kind, filename)}\n`);
+            process.exit(0);
+        });
+    }
+}
+/*  MCP registration entry point for artifact tools  */
+export class ArtifactMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register MCP tools  */
+    register(mcp) {
+        mcp.registerTool("ase_artifact_list", {
+            title: "ASE artifact list",
+            description: "Resolve one or more artifact `kind`s to project-relative file lists. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, `infr`, and `othr`. " +
+                "Returns an `artifacts` array of `{ kind, files }` objects. " +
+                "If `kind` is omitted or empty, all kinds are resolved.",
+            inputSchema: {
+                kind: z.array(z.string()).optional()
+                    .describe("list of artifact kinds (`spec`, `arch`, `code`, `docs`, `infr`, " +
+                    "`othr`); if omitted or empty, all kinds are resolved")
+            },
+            outputSchema: {
+                artifacts: z.array(z.object({
+                    kind: z.string().describe("artifact kind"),
+                    files: z.array(z.string()).describe("project-relative file paths for the kind")
+                })).describe("resolved artifacts, one entry per requested kind")
+            }
+        }, async (args) => {
+            try {
+                const requested = args.kind !== undefined && args.kind.length > 0 ?
+                    args.kind : [...artifactKinds];
+                const kinds = requested.map((k) => Artifact.validateKind(k));
+                const result = { artifacts: Artifact.list(this.log, kinds) };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("ase_artifact_name", {
+            title: "ASE artifact name",
+            description: "Resolve a base-relative `filename` within an artifact `kind` to a project-relative path " +
+                "by prefixing it with the kind's configured `basedir`. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, and `infr` " +
+                "(the implicit `othr` catch-all has no basedir and is rejected). " +
+                "If `kind` is omitted, it defaults to `code`. " +
+                "Returns the resolved path as `name`.",
+            inputSchema: {
+                kind: z.string().optional()
+                    .describe("artifact kind (`spec`, `arch`, `code`, `docs`, `infr`); defaults to `code`"),
+                filename: z.string()
+                    .describe("base-relative filename within the kind's basedir")
+            },
+            outputSchema: {
+                name: z.string().describe("project-relative file path")
+            }
+        }, async (args) => {
+            try {
+                const kind = Artifact.validateKind(args.kind ?? "code");
+                const result = { name: Artifact.name(this.log, kind, args.filename) };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-config.js

@@ -25,29 +25,41 @@ export const agentClassification = {
 /*  classification presets  */
 export const projectClassificationPresets = {
     vibe: {
+        "agent.persona": "writer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "black",
-        "agent.persona": "writer"
+        "project.boxing": "black"
     },
     pro: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "white",
-        "agent.persona": "engineer"
+        "project.boxing": "white"
     },
     default: {
+        "agent.task": "default",
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
         "project.boxing": "white",
-        "agent.persona": "engineer",
-        "agent.task": "default"
+        "project.artifact.task.basedir": ".ase/task",
+        "project.artifact.task.files": "*.md",
+        "project.artifact.spec.basedir": "doc/spec",
+        "project.artifact.spec.files": "*.{md,txt}",
+        "project.artifact.arch.basedir": "doc/arch",
+        "project.artifact.arch.files": "*.{md,txt}",
+        "project.artifact.code.basedir": "src",
+        "project.artifact.code.files": "** !**/etc/** !**/{.gitignore,.npmignore,package.json}",
+        "project.artifact.docs.basedir": "doc",
+        "project.artifact.docs.files": "** **/{README,LICENSE,CHANGELOG}.{md,txt} !{spec,arch}/**",
+        "project.artifact.infr.basedir": "",
+        "project.artifact.infr.files": "**/{.github,.claude*,etc}/** **/{AGENTS.md,{package,tsconfig*}.json,.{git,npm}ignore}"
     },
     industry: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "grey",
-        "agent.persona": "engineer"
+        "project.boxing": "grey"
     }
 };
 /*  hard-coded map: which scope kinds each variable may be SET on
@@ -55,7 +67,19 @@ export const projectClassificationPresets = {
     keys absent from this map default to all non-"default" scope kinds  */
 export const configWritableScopes = {
     "agent.task": ["session"],
-    "agent.skill": ["session"]
+    "agent.skill": ["session"],
+    "project.artifact.task.basedir": ["user", "project"],
+    "project.artifact.task.files": ["user", "project"],
+    "project.artifact.spec.basedir": ["user", "project"],
+    "project.artifact.spec.files": ["user", "project"],
+    "project.artifact.arch.basedir": ["user", "project"],
+    "project.artifact.arch.files": ["user", "project"],
+    "project.artifact.code.basedir": ["user", "project"],
+    "project.artifact.code.files": ["user", "project"],
+    "project.artifact.docs.basedir": ["user", "project"],
+    "project.artifact.docs.files": ["user", "project"],
+    "project.artifact.infr.basedir": ["user", "project"],
+    "project.artifact.infr.files": ["user", "project"]
 };
 /*  default set of scope kinds writable for any unrestricted key  */
 const configWritableScopesDefault = ["user", "project", "task", "session"];
@@ -130,7 +154,15 @@ export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
         id: v.optional(v.pipe(v.string(), v.minLength(1))),
         name: v.optional(v.pipe(v.string(), v.minLength(1))),
-        boxing: v.optional(v.picklist(projectClassification.boxing))
+        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()) }))
+        }))
     })),
     agent: v.optional(v.strictObject({
         persona: v.optional(v.picklist(agentClassification.persona)),
@@ -614,6 +646,20 @@ export default class ConfigCommand {
                 cfg.write();
             });
         });
+        /*  register CLI sub-command "ase config delete"  */
+        configCmd
+            .command("delete")
+            .description("delete the value at a dotted configuration key")
+            .argument("<key>", "configuration key (dotted path)")
+            .action((key, _opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
+            const cfg = new Config("config", configSchema, this.log, scope);
+            cfg.lock(() => {
+                cfg.read();
+                cfg.delete(key);
+                cfg.write();
+            });
+        });
     }
 }
 /*  MCP registration entry point for layered YAML configuration access  */

package/dst/ase-markdown.js

@@ -0,0 +1,235 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import { z } from "zod";
+/*  the reusable functionality  */
+export class Markdown {
+    /*  prepare Markdown for improved rendering by rewriting
+        unordered bullet paragraphs -- replacing the "-"/"*" bullet marker with
+        "◯" and splitting multi-line inline code spans into per-line single-line
+        spans (so each physical line carries its own closed backtick span).
+        Fenced code blocks (``` / ~~~) are detected line-wise and passed
+        through entirely verbatim, so neither the inline-span splitting nor the
+        bullet-marker rewriting ever touches their contents.  */
+    static prepare(text) {
+        if (typeof text !== "string")
+            throw new Error("markdown: text must be a string");
+        /*  segment the input line-wise into alternating non-fenced and
+            fenced regions: a fenced code block opens with a line whose first
+            non-whitespace content is a run of 3+ backticks or tildes and
+            closes with a matching-or-longer run of the same marker; fenced
+            regions are emitted verbatim while only non-fenced regions are
+            handed to the rewriting passes below  */
+        const lines = text.split("\n");
+        let result = "";
+        let buf = "";
+        let inFence = false;
+        let fenceCh = "";
+        let fenceLen = 0;
+        const flush = () => {
+            if (buf !== "") {
+                result += Markdown.rewrite(buf);
+                buf = "";
+            }
+        };
+        for (let li = 0; li < lines.length; li++) {
+            const line = lines[li];
+            const nl = li < lines.length - 1 ? "\n" : "";
+            const m = line.match(/^(\s*)(`{3,}|~{3,})/);
+            if (!inFence && m) {
+                /*  a fence-opening line: flush the pending non-fenced buffer,
+                    enter fenced mode, and emit the opener verbatim  */
+                flush();
+                inFence = true;
+                fenceCh = m[2][0];
+                fenceLen = m[2].length;
+                result += line + nl;
+            }
+            else if (inFence) {
+                /*  inside a fenced block: emit verbatim and, on a matching
+                    closing fence line, leave fenced mode  */
+                result += line + nl;
+                const c = line.match(/^(\s*)(`{3,}|~{3,})\s*$/);
+                if (c && c[2][0] === fenceCh && c[2].length >= fenceLen)
+                    inFence = false;
+            }
+            else
+                /*  a regular non-fenced line: accumulate for the passes  */
+                buf += line + nl;
+        }
+        flush();
+        return result;
+    }
+    /*  apply the inline-span and bullet-marker rewriting passes to a chunk of
+        non-fenced Markdown text (see prepare() for fenced-block handling)  */
+    static rewrite(text) {
+        /*  PASS 1: rewrite single-backtick inline code spans that carry
+            backslash-escaped backticks (`\``) into CommonMark-correct spans.  */
+        {
+            let pre = "";
+            let j = 0;
+            while (j < text.length) {
+                const ch = text[j];
+                if (ch !== "`") {
+                    /*  literal backslash-escaped backtick *outside* any span
+                        is left verbatim for later scanning  */
+                    pre += ch;
+                    j++;
+                    continue;
+                }
+                /*  scan an opening single-backtick span, capturing its raw
+                    inner content up to the matching unescaped close backtick  */
+                let inner = "";
+                let k = j + 1;
+                let closed = false;
+                let escaped = false;
+                while (k < text.length) {
+                    const c = text[k];
+                    if (c === "\\" && k + 1 < text.length && text[k + 1] === "`") {
+                        inner += "\\`";
+                        escaped = true;
+                        k += 2;
+                        continue;
+                    }
+                    if (c === "`") {
+                        closed = true;
+                        break;
+                    }
+                    inner += c;
+                    k++;
+                }
+                if (!closed || !escaped) {
+                    /*  not an escaped-backtick span: emit the opening backtick
+                        verbatim and continue scanning from just after it  */
+                    pre += "`";
+                    j++;
+                    continue;
+                }
+                /*  un-escape inner `\`` into literal backticks, then choose a
+                    fence longer than the longest internal backtick run  */
+                const content = inner.replace(/\\`/g, "`");
+                let maxRun = 0;
+                let run = 0;
+                for (const c of content) {
+                    if (c === "`") {
+                        run++;
+                        if (run > maxRun)
+                            maxRun = run;
+                    }
+                    else
+                        run = 0;
+                }
+                const fence = "`".repeat(maxRun + 1);
+                const pad = (content.startsWith("`") || content.endsWith("`")) ? " " : "";
+                pre += `${fence}${pad}${content}${pad}${fence}`;
+                j = k + 1;
+            }
+            text = pre;
+        }
+        /*  PASS 2: split multi-line inline code spans by scanning the
+            entire text character-by-character while tracking whether we
+            are currently inside an active backtick (U+0060) span; on
+            every "<newline><whitespaces>" sequence encountered while
+            inside a span, close the span before the break and re-open
+            it after the indentation, so each physical line becomes its
+            own single-line span */
+        let out = "";
+        let fence = 0;
+        let i = 0;
+        while (i < text.length) {
+            const ch = text[i];
+            if (ch === "`") {
+                /*  measure the full backtick run (a code-span delimiter is a
+                    *run* of backticks; a span opened by N backticks is closed
+                    only by a run of exactly N backticks)  */
+                let n = 0;
+                while (i < text.length && text[i] === "`") {
+                    n++;
+                    i++;
+                }
+                if (fence === 0)
+                    /*  open a span of fence width n  */
+                    fence = n;
+                else if (n === fence)
+                    /*  close the active span  */
+                    fence = 0;
+                out += "`".repeat(n);
+                continue;
+            }
+            if (fence > 0 && (ch === "\r" || ch === "\n")) {
+                /*  consume optional CR followed by mandatory LF  */
+                let nl = "";
+                if (ch === "\r" && i + 1 < text.length && text[i + 1] === "\n") {
+                    nl = "\r\n";
+                    i += 2;
+                }
+                else if (ch === "\n") {
+                    nl = "\n";
+                    i++;
+                }
+                else {
+                    /*  bare CR: not a recognized newline, pass through  */
+                    out += ch;
+                    i++;
+                    continue;
+                }
+                /*  consume the following run of SPACE/TAB whitespace  */
+                let ws = "";
+                while (i < text.length && (text[i] === " " || text[i] === "\t")) {
+                    ws += text[i];
+                    i++;
+                }
+                /*  close span before the break, re-open after indentation,
+                    preserving the active fence width on both sides  */
+                const bars = "`".repeat(fence);
+                out += `${bars}${nl}${ws}${bars}`;
+                continue;
+            }
+            out += ch;
+            i++;
+        }
+        /*  PASS 3: replace the leading "-"/"*" marker of every unordered
+            bullet paragraph with "◯", preserving the leading indentation
+            and the following whitespace; operate line-by-line so only the
+            actual list markers (at a line start) are affected  */
+        out = out
+            .split("\n")
+            .map((line) => line.replace(/^(\s*)[-*]([ \t]+)/, "$1◯$2"))
+            .join("\n");
+        return out;
+    }
+}
+/*  MCP registration entry point  */
+export class MarkdownMCP {
+    register(mcp) {
+        mcp.registerTool("ase_markdown_prepare", {
+            title: "ASE markdown prepare",
+            description: "Prepare Markdown `text` for improved rendering by rewriting " +
+                "unordered bullet paragraphs: replace the `-`/`*` bullet markers with `◯` " +
+                "and split multi-line inline code spans into per-line single-line spans. " +
+                "Single-backtick spans containing backslash-escaped backticks are rewritten " +
+                "into CommonMark-correct spans with a widened backtick fence and literal inner " +
+                "backticks. Returns the prepared Markdown as `text`.",
+            inputSchema: {
+                text: z.string()
+                    .describe("Markdown text to prepare for improved rendering")
+            }
+        }, async (args) => {
+            try {
+                const text = Markdown.prepare(args.text);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}