@rse/ase 0.9.55 → 0.9.57

package/dst/ase-config.js

@@ -124,27 +124,33 @@ const gitToplevel = () => {
     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  */
-const hasProjectContext = () => {
-    if (gitToplevel() !== null)
-        return true;
+/*  determine the project root directory, i.e. either the top-level
+    directory of the Git working tree or the nearest directory at or
+    above cwd which carries a ".ase" directory  */
+const projectRoot = () => {
+    const top = gitToplevel();
+    if (top !== null)
+        return top;
     let dir = fs.realpathSync(process.cwd());
     for (;;) {
         if (fs.existsSync(path.join(dir, ".ase")))
-            return true;
+            return dir;
         const parent = path.dirname(dir);
         if (parent === dir)
-            return false;
+            return null;
         dir = parent;
     }
 };
+/*  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  */
+const hasProjectContext = () => projectRoot() !== null;
 /*  parse a raw "--scope" option value into a canonical Scope chain;
     accepts a comma-separated list of terms in any order. The "user"
     term is always implicitly added at the bottom of the chain; the
     "project" term is implicitly added only when a project context
-    exists (Git repository or ".ase" directory at or above cwd), and
-    an explicit "project" term requires that same context  */
+    exists (Git repository or ".ase" directory at or above cwd) and it
+    stays weaker than the strongest explicitly requested term, and an
+    explicit "project" term requires that same context  */
 export const parseScope = (value) => {
     const projectActive = hasProjectContext();
     const input = (value === undefined || value === "") ?
@@ -162,7 +168,11 @@ export const parseScope = (value) => {
     if (seen.has("project") && !projectActive)
         throw new Error("invalid --scope: \"project\" requires a project context " +
             "(a Git repository or a \".ase\" directory at or above the current directory)");
-    if (!seen.has("project") && projectActive)
+    /*  the strongest term of the chain is the write target, so an implicitly
+        added "project" term must never outrank the strongest explicitly
+        requested term, as this would silently retarget the caller's request  */
+    const rankMax = Math.max(...terms.map((t) => scopeRank(t.kind)));
+    if (!seen.has("project") && projectActive && rankMax > scopeRank("project"))
         terms.unshift({ kind: "project" });
     if (!seen.has("user"))
         terms.unshift({ kind: "user" });
@@ -210,6 +220,7 @@ export class Config {
     log;
     docs;
     target;
+    pruned;
     /*  creation  */
     constructor(name, schema, log, scope = [{ kind: "user" }, { kind: "project" }]) {
         if (scope.length === 0)
@@ -222,6 +233,7 @@ export class Config {
         this.filename = this.resolveFilename(name, tgt);
         this.docs = [{ scope: tgt, filename: this.filename, doc: new Document() }];
         this.target = 0;
+        this.pruned = [];
     }
     /*  render a scope term as a short textual label  */
     static scopeLabel(term) {
@@ -252,16 +264,13 @@ export class Config {
             return path.join(this.userConfigDir(), `${name}.yaml`);
         else if (term.kind === "project") {
             const rel = path.join(".ase", `${name}.yaml`);
-            const cwd = process.cwd();
-            const top = gitToplevel();
-            const found = top !== null ?
-                this.findUpward(cwd, top, rel) :
-                (fs.existsSync(path.join(cwd, rel)) ? path.join(cwd, rel) : null);
-            return found ?? path.join(top ?? cwd, rel);
+            const root = projectRoot() ?? process.cwd();
+            const found = this.findUpward(process.cwd(), root, rel);
+            return found ?? path.join(root, rel);
         }
         else if (term.kind === "task") {
-            const top = gitToplevel() ?? process.cwd();
-            return path.join(top, ".ase", "task", term.id, `${name}.yaml`);
+            const root = projectRoot() ?? process.cwd();
+            return path.join(root, ".ase", "task", term.id, `${name}.yaml`);
         }
         else
             return path.join(os.homedir(), ".ase", "session", term.id, `${name}.yaml`);
@@ -290,6 +299,7 @@ export class Config {
     read(mode = "lenient") {
         const chain = this.scope;
         const docs = [];
+        this.pruned = [];
         for (let i = 0; i < chain.length; i++) {
             const sc = chain[i];
             if (sc.kind === "default") {
@@ -321,6 +331,8 @@ export class Config {
                 if (perDocMode === "strict")
                     throw new Error(msg);
                 this.log.write("warning", msg);
+                if (isTarget)
+                    this.pruned.push(`unparsable YAML (${doc.errors[0].message.split("\n")[0]})`);
                 doc = new Document();
             }
             docs.push({ scope: sc, filename, doc });
@@ -330,7 +342,9 @@ export class Config {
         for (let i = 0; i < docs.length; i++) {
             const isTarget = (i === this.target);
             const perDocMode = isTarget ? mode : "lenient";
-            this.validateDoc(docs[i].doc, docs[i].filename, perDocMode);
+            const removed = this.validateDoc(docs[i].doc, docs[i].filename, perDocMode);
+            if (isTarget)
+                this.pruned.push(...removed);
         }
     }
     /*  acquire a cross-process advisory lock on the target scope's file,
@@ -355,18 +369,28 @@ export class Config {
         const td = this.docs[this.target];
         if (td.scope.kind === "default")
             throw new Error("internal error: \"default\" scope is not writable");
+        /*  a lenient read physically removes the invalid content from the in-memory
+            target document, so writing that document back would silently erase the
+            very same content from the file on disk  */
+        if (this.pruned.length > 0)
+            throw new Error(`refusing to overwrite ${td.filename}: it carries invalid content ` +
+                `(${this.pruned.join(", ")}) which was skipped on reading and hence would be ` +
+                "lost on writing -- repair the file first");
         this.validateDoc(td.doc, td.filename, "strict");
         fs.mkdirSync(path.dirname(td.filename), { recursive: true });
         writeFileAtomic.sync(td.filename, td.doc.toString({ indent: 4 }), { encoding: "utf8" });
     }
-    /*  validate a single YAML document against the optional schema  */
+    /*  validate a single YAML document against the optional schema; in "strict"
+        mode all invalid entries are reported as a thrown error, in "lenient" mode
+        they are removed from the document and their dotted paths are returned  */
     validateDoc(doc, filename, mode = "strict") {
         if (this.schema === null)
-            return;
+            return [];
+        const removed = [];
         for (;;) {
             const result = v.safeParse(this.schema, doc.toJS());
             if (result.success)
-                return;
+                return removed;
             if (mode === "strict") {
                 const issues = result.issues.map((i) => {
                     const dotPath = (i.path ?? []).map((p) => String(p.key)).join(".");
@@ -374,19 +398,20 @@ export class Config {
                 }).join("; ");
                 throw new Error(`invalid configuration in ${filename}: ${issues}`);
             }
-            let progressed = false;
+            const before = removed.length;
             for (const i of result.issues) {
                 const segs = (i.path ?? []).map((p) => String(p.key));
                 const dotPath = segs.join(".");
                 this.log.write("warning", `invalid entry in ${filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}`);
-                if (segs.length > 0) {
-                    doc.deleteIn(segs);
-                    progressed = true;
-                }
-                /*  root-level issues cannot be deleted; processing continues with the remaining issues  */
+                if (segs.length > 0 && doc.deleteIn(segs))
+                    removed.push(dotPath);
+                /*  issues at the document root and issues whose stringified path does not
+                    address a deletable node (e.g. a non-string YAML key like "404:", which
+                    "toJS" stringifies) cannot be removed; processing continues with the
+                    remaining issues  */
             }
-            if (!progressed)
-                return;
+            if (removed.length === before)
+                return removed;
         }
     }
     /*  enumerate all full dotted leaf paths from the attached valibot schema  */
@@ -444,6 +469,21 @@ export class Config {
         }
         return undefined;
     }
+    /*  retrieve the explicitly configured value at a dotted key, i.e. the same
+        cascade as "get", but skipping the built-in "default" scope layer, so
+        callers can distinguish a deliberately configured value from a merely
+        preset one  */
+    getExplicit(key) {
+        const segs = this.resolveKey(key).split(".");
+        for (let i = this.docs.length - 1; i >= 0; i--) {
+            if (this.docs[i].scope.kind === "default")
+                continue;
+            const node = this.docs[i].doc.getIn(segs);
+            if (node !== undefined)
+                return node;
+        }
+        return undefined;
+    }
     /*  enumerate the effective leaf entries across the full scope chain;
         each returned entry identifies the originating scope  */
     entries() {
@@ -551,7 +591,8 @@ export default class ConfigCommand {
             .option("--scope <scope>", "configuration scope chain: comma-separated list of \"user\", \"project\", " +
             "\"task:<id>\", and/or \"session:<id>\" terms (e.g. \"task:N,session:M\"); " +
             "\"user\" is always implicitly included and \"project\" is implicitly " +
-            "included whenever a project context (Git repo or upward \".ase\" directory) exists")
+            "included whenever a project context (Git repo or upward \".ase\" directory) exists, " +
+            "but never above the strongest explicitly requested term")
             .description("manage ASE configuration")
             .action(() => {
             configCmd.outputHelp();

package/dst/ase-getopt.js

@@ -7,7 +7,7 @@ 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  */
+    the quoting and escaping so the original text can later be sliced verbatim  */
 const tokenizeRanges = (input) => {
     const ranges = [];
     let i = 0;
@@ -30,6 +30,8 @@ const tokenizeRanges = (input) => {
                 if (i < input.length)
                     i++;
             }
+            else if (ch === "\\" && i + 1 < input.length)
+                i += 2;
             else
                 i++;
         }

package/dst/ase-hook.js

@@ -240,10 +240,12 @@ export default class HookCommand {
         const projectId = path.basename(projectDir);
         /*  determine user id  */
         const userId = process.env.USER ?? process.env.LOGNAME ?? "unknown";
-        /*  helper function: determine a setting from the configuration,
-            falling back to an environment variable and a default  */
+        /*  helper function: determine a setting from the explicitly configured
+            scopes, falling back to an environment variable and a default; the
+            built-in "default" scope layer is deliberately skipped, as its preset
+            value is always present and would hence shadow the environment variable  */
         const setting = (key, envVar, dflt) => {
-            const val = cfg.get(key);
+            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  */

package/dst/ase-markdown.js

@@ -19,9 +19,12 @@ export class Markdown {
         /*  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  */
+            closes with a matching-or-longer run of the same marker; for a
+            backtick fence the info string trailing the run must not carry any
+            further backtick, so an inline code span delimited by a run of 3+
+            backticks never opens a fence; 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 = "";
@@ -37,7 +40,7 @@ export class Markdown {
         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,})/);
+            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  */

package/dst/ase-service.js

@@ -439,7 +439,7 @@ export default class ServiceCommand {
             return await new Promise(() => { });
         }
         if (port !== null) {
-            const match = await probe(port, ctx.projectId);
+            const match = await probe(port, ctx.projectId).catch(() => null);
             if (match === true) {
                 this.log.write("info", `service: already running on port ${port}`);
                 return 0;

package/dst/ase-setup.js

@@ -808,9 +808,11 @@ export default class SetupCommand {
         /*  default for --dev derived from ASE_SETUP_DEV environment variable  */
         const envDev = process.env.ASE_SETUP_DEV ?? "";
         const devDflt = envDev !== "" && envDev !== "0" && envDev.toLowerCase() !== "false";
-        /*  default for --tool derived from ASE_TOOL environment variable  */
+        /*  default for --tool derived from ASE_TOOL environment variable
+            (validated lazily by "parseTool" in each action, so an invalid
+            value cannot break unrelated "ase" commands at startup)  */
         const envTool = process.env.ASE_TOOL ?? "";
-        const toolDflt = envTool !== "" ? this.parseTool(envTool) : "claude";
+        const toolDflt = envTool !== "" ? envTool : "claude";
         /*  register CLI top-level command "ase setup"  */
         const setupCmd = program
             .command("setup")

package/dst/ase-statusline.js

@@ -388,25 +388,23 @@ export default class StatuslineCommand {
                 /*  ==== RATE LIMITS ====  */
                 S: () => {
                     const pct5h = data.rate_limits?.five_hour?.used_percentage;
-                    if (pct5h !== undefined)
-                        emit(`${prefix("⏲", "session-usage")}${c.bold(`${pct5h.toFixed(1)}%`)}`);
+                    const s = pct5h !== undefined ? `${pct5h.toFixed(1)}%` : "-";
+                    emit(`${prefix("⏲", "5h-usage")}${c.bold(s)}`);
                 },
                 D: () => {
                     const until5h = data.rate_limits?.five_hour?.resets_at;
                     const s = formatTimeUntil(until5h);
-                    if (s !== "")
-                        emit(`${prefix("⏱", "session-resets")}${c.bold(s)}`);
+                    emit(`${prefix("⏱", "5h-resets")}${c.bold(s !== "" ? s : "-")}`);
                 },
                 W: () => {
                     const pctWk = data.rate_limits?.seven_day?.used_percentage;
-                    if (pctWk !== undefined)
-                        emit(`${prefix("⏲", "weekly-usage")}${c.bold(`${pctWk.toFixed(1)}%`)}`);
+                    const s = pctWk !== undefined ? `${pctWk.toFixed(1)}%` : "-";
+                    emit(`${prefix("⏲", "7d-usage")}${c.bold(s)}`);
                 },
                 Q: () => {
                     const untilWk = data.rate_limits?.seven_day?.resets_at;
                     const s = formatTimeUntil(untilWk);
-                    if (s !== "")
-                        emit(`${prefix("⏱", "weekly-resets")}${c.bold(s)}`);
+                    emit(`${prefix("⏱", "7d-resets")}${c.bold(s !== "" ? s : "-")}`);
                 },
                 /*  ==== COSTS ====  */
                 H: () => {

package/dst/ase-task.js

@@ -334,6 +334,7 @@ export class Task {
     /*  set the active task id for a given session  */
     static setId(log, session, id) {
         Task.validateSession(session);
+        Task.validateId(id);
         const scope = parseScope(`session:${session}`);
         const cfg = new Config("config", configSchema, log, scope);
         cfg.lock(() => {
@@ -529,15 +530,33 @@ export class TaskMCP {
             title: "ASE task load",
             description: "Load a previously persisted task by `id`. " +
                 "Returns the task as `text`, normalized into the current Markdown frontmatter shape; " +
-                "returns an empty string if no task exists for the `id`.",
+                "returns an empty string if no task exists for the `id`. " +
+                "The `variant` argument selects the returned form of the plan: " +
+                "`source` (the default) is the *authoring* form and the *only* form which may be " +
+                "edited and passed back into `ase_task_save`; " +
+                "`render` is the *rendering-prepared* form, which is for *display only* and " +
+                "MUST NOT be persisted; " +
+                "`both` returns the source form enclosed in `<task-plan-source>` delimiter lines, " +
+                "followed by the render form enclosed in `<task-plan-render>` delimiter lines.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
+                variant: z.enum(["source", "render", "both"]).optional()
+                    .describe("returned form of the plan: `source` (authoring form, the default), " +
+                    "`render` (rendering-prepared form, display only), or `both` " +
+                    "(both forms, each enclosed in its delimiter lines)")
             }
         }, async (args) => {
             try {
-                const raw = Task.load(this.log, args.id);
-                const text = Markdown.prepare(raw);
+                const source = Task.load(this.log, args.id);
+                const variant = args.variant ?? "source";
+                let text = source;
+                if (source !== "" && variant === "render")
+                    text = Markdown.prepare(source);
+                else if (source !== "" && variant === "both")
+                    text =
+                        `<task-plan-source>\n${source}\n</task-plan-source>\n\n` +
+                            `<task-plan-render>\n${Markdown.prepare(source)}\n</task-plan-render>\n`;
                 return {
                     content: [{ type: "text", text }]
                 };
@@ -550,21 +569,28 @@ export class TaskMCP {
         mcp.registerTool("ase_task_save", {
             title: "ASE task save",
             description: "Persist a task as `text` under `id`. " +
-                "Overwrites any existing task for the same `id`. " +
-                "Returns the persisted task as `text`, prepared for improved rendering.",
+                "The `text` MUST be the *authoring* form of the plan (as returned by the " +
+                "`source` variant of `ase_task_load`) and hence MUST NOT carry any rendering " +
+                "artifacts. Overwrites any existing task for the same `id`. " +
+                "Returns a status `text` by default, or, if `render` is `true`, the " +
+                "*rendering-prepared* form of the just-saved plan, for display purposes only.",
             inputSchema: {
                 id: z.string()
                     .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
                 text: z.string()
-                    .describe("text content of the task")
+                    .describe("text content of the task, in its authoring form"),
+                render: z.boolean().optional()
+                    .describe("if true, return the rendering-prepared form of the just-saved " +
+                    "plan instead of a status message (default: false)")
             }
         }, async (args) => {
             try {
                 Task.save(this.log, args.id, args.text);
-                /*  return the prepared content, so a caller reusing the
-                    just-saved plan instead of re-loading it still receives
-                    the rendering-prepared variant  */
-                const text = Markdown.prepare(args.text);
+                /*  return the rendering-prepared content on demand, so a caller
+                    displaying the just-saved plan does not have to re-load it  */
+                const text = (args.render ?? false) ?
+                    Markdown.prepare(args.text) :
+                    `OK: saved task "${args.id}"`;
                 return {
                     content: [{ type: "text", text }]
                 };

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.55",
+    "version":                              "0.9.57",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -18,12 +18,12 @@
     "devDependencies": {
         "eslint":                           "9.39.4",
         "@eslint/js":                       "9.39.4",
-        "@typescript-eslint/parser":        "8.65.0",
-        "@typescript-eslint/eslint-plugin": "8.65.0",
+        "@typescript-eslint/parser":        "8.66.0",
+        "@typescript-eslint/eslint-plugin": "8.66.0",
         "eslint-plugin-promise":            "7.3.0",
         "eslint-plugin-import":             "2.32.0",
         "neostandard":                      "0.13.0",
-        "globals":                          "17.8.0",
+        "globals":                          "17.9.0",
         "typescript":                       "6.0.3",
 
         "@rse/stx":                         "1.1.6",
@@ -42,7 +42,7 @@
     },
     "dependencies": {
         "commander":                        "15.0.0",
-        "@dotenvx/dotenvx":                 "2.19.1",
+        "@dotenvx/dotenvx":                 "2.19.2",
         "yaml":                             "2.9.0",
         "valibot":                          "1.4.2",
         "execa":                            "10.0.1",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.55",
+    "version":     "0.9.57",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.55",
+    "version":     "0.9.57",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.55",
+    "version":     "0.9.57",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/agents/ase-code-analyze.md

@@ -63,7 +63,7 @@ Workflow
         -   incorrect short-circuit evaluation or operator precedence
         -   logical vs. bitwise operator confusion
         -   negation mistakes in compound predicates
-        -   wrong comparison operator (`==` instead of `===`, `<` vs. `<=`, etc)
+        -   wrong comparison operator (`==` instead of `===`, `<` vs. `<=`, etc.)
         -   inverted condition or swapped if/else branches
         -   dead or duplicated conditional branches
         -   fall-through where a break or return was intended

package/plugin/agents/ase-code-lint.md

@@ -65,10 +65,10 @@ Workflow
         identifiers, string literals and comments.
 
         Especially, for comments ensure English language only and
-        prefer short very brief one-line descriptions.
+        prefer short, very brief one-line descriptions.
 
     -   **A05 - COMPLEXITY**:
-        Check for extremely long functions, and deeply nested code
+        Check for extremely long functions and deeply nested code
         constructs.
 
         Especially, for functions prefer fewer than 100 lines, and for
@@ -185,8 +185,8 @@ Workflow
     -   **A15 - PERFORMANCE**:
         Check for bad performance and inefficiency issues.
 
-        Especially, check for code constructs with a high (i.e., not
-        constant/O(1), or linear/O(n) complexity) in its execution time
+        Especially, check for code constructs with a high complexity (i.e., not
+        constant/O(1), or linear/O(n)) in their execution time
         and/or memory consumption.
 
     -   **A16 - SECURITY**:

package/plugin/agents/ase-meta-chat.md

@@ -56,5 +56,5 @@ tools:
 4.  Now call the MCP tool `query(prompt: <query/>)` from the MCP server
     <server/> and then return its result `text` *verbatim* and *without
     any modifications* as the last message. Especially, do *NOT* add or
-    remove any text to the MCP server response on your own and do not
+    remove any text to or from the MCP server response on your own and do not
     interpret the result in any way.

package/plugin/agents/ase-meta-proximity.md

@@ -102,7 +102,7 @@ store those facts in the placeholder named `<arg2/>`.
         <child-4/>.
 
         <expand name="gather-facts"
-            arg1="the CHILDREN topics (narrower topics that are specializations) of the following topic: <topic/>"
+            arg1="the CHILD topics (narrower topics that are specializations) of the following topic: <topic/>"
             arg2="facts-children"></expand>
 
         Ground the determination of the canonical names of the most