@rse/ase 1.0.7 → 2.0.0

package/dst/ase-agent.js

@@ -0,0 +1,65 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { builtinKinds, discoverKinds } from "./ase-agent-definition-core.js";
+import AgentAdhoc, { AgentBuiltin, AgentOfDefinition } from "./ase-agent-runtime-engine.js";
+import AgentProcessCommand from "./ase-agent-process.js";
+import AgentRelayCommand from "./ase-agent-relay-server-cli.js";
+import AgentFleetCommand from "./ase-agent-fleet.js";
+/*  CLI command "ase agent"  */
+export default class AgentCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register command  */
+    register(program) {
+        /*  the available agent kinds, each with the creation of a fresh agent: the built-in
+            kinds (each the agent of its declarative definitions), the ad-hoc kind, and the
+            definition kinds of the user and the project (see below)  */
+        const kinds = new Map([
+            ...builtinKinds.map((spec) => () => new AgentBuiltin(this.log, spec)),
+            () => new AgentAdhoc(this.log)
+        ].map((create) => [create().kind, create]));
+        /*  register CLI top-level command "ase agent"  */
+        const cmd = program
+            .command("agent")
+            .description("Autonomous agents driving the task lifecycle phases (implementer, qualifier, integrator), " +
+            "rebooting and condensing the plans of tasks (rebooter, condenser), " +
+            "processing the edit requests of tasks (editor), estimating the effort of tasks (estimator), " +
+            "researching the plans and topics of tasks (researcher), " +
+            "or of the definitions of the user or the project " +
+            "(\".ase/agents/<kind>.{yaml,ts,js}\") or given ad-hoc (adhoc), " +
+            "each running in its own process, individually or as a fleet, optionally reporting to the agent relay")
+            .action(() => {
+            cmd.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command groups "ase agent <kind>" (of the built-in and
+            the ad-hoc kinds), "ase agent relay", and "ase agent fleet"  */
+        for (const create of kinds.values())
+            new AgentProcessCommand(this.log, create(), kinds).register(cmd);
+        new AgentRelayCommand(this.log).register(cmd);
+        new AgentFleetCommand(this.log, kinds).register(cmd);
+        /*  register CLI sub-command groups "ase agent <kind>" of the definition kinds of
+            the user and the project on the dispatch of "ase agent" only, as their discovery
+            scans the file system, where a definition kind replaces a built-in kind  */
+        program.hook("preSubcommand", (_program, sub) => {
+            if (sub !== cmd)
+                return;
+            const commands = cmd.commands;
+            for (const spec of discoverKinds(this.log, ["adhoc", "relay", "fleet"])) {
+                const shadowed = commands.findIndex((command) => command.name() === spec.kind);
+                const create = () => new AgentOfDefinition(this.log, spec, shadowed >= 0);
+                kinds.set(spec.kind, create);
+                if (shadowed >= 0)
+                    commands.splice(shadowed, 1);
+                new AgentProcessCommand(this.log, create(), kinds).register(cmd);
+                if (shadowed >= 0)
+                    commands.splice(shadowed, 0, commands.pop());
+            }
+        });
+    }
+}

package/dst/ase-artifact.js

@@ -8,10 +8,11 @@ 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 { Config } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
 import { Task } from "./ase-task.js";
-import { Ignore } from "./ase-ignore.js";
-import { writeStdout } from "./ase-stdio.js";
+import { Ignore } from "./ase-lib-ignore.js";
+import { writeStdout } from "./ase-lib-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", "code", "docs", "infr", "othr"];
@@ -89,8 +90,8 @@ export class Artifact {
         for a single kind; "basedir" is project-root-relative (POSIX,
         "" ≡ project root) and "files" resolves relative to "basedir"  */
     static spec(cfg, kind) {
-        const basedir = Artifact.configString(cfg, `project.artifact.${kind}.basedir`)
-            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
+        const basedir = path.posix.normalize(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`);

package/dst/ase-config-core.js

@@ -0,0 +1,465 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { Document, parseDocument, isMap, isScalar } from "yaml";
+import * as v from "valibot";
+import writeFileAtomic from "write-file-atomic";
+import lockfile from "proper-lockfile";
+import { projectRoot, userConfigDir, userStateDir } from "./ase-config-scope.js";
+import { projectClassificationPresets, configWritableScopes, configWritableScopesDefault, configSecretKeys, sessionStateSchema } from "./ase-config-schema.js";
+/*  encapsulate read/write access to a stack of "<name>.yaml" configuration files,
+    each associated with a scope term; reads cascade along user < project < task < session,
+    writes are confined to the target (strongest) scope term  */
+export class Config {
+    /*  public state  */
+    filename;
+    /*  private state  */
+    name;
+    scope;
+    schema;
+    log;
+    docs;
+    target;
+    pruned;
+    locked = null;
+    /*  creation  */
+    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;
+        this.scope = scope[0].kind === "default" ? scope : [{ kind: "default" }, ...scope];
+        this.schema = schema ?? null;
+        this.log = log;
+        const tgt = this.scope[this.scope.length - 1];
+        this.filename = this.resolveFilename(name, tgt);
+        this.docs = [{ scope: tgt, filename: this.filename, doc: new Document() }];
+        this.target = 0;
+        this.pruned = [];
+    }
+    /*  the configuration files of the scope chain (after reading)  */
+    files() {
+        return this.docs.map((layer) => layer.filename).filter((filename) => filename !== "");
+    }
+    /*  render a scope term as a short textual label  */
+    static scopeLabel(term) {
+        if (term.kind === "default" || term.kind === "user" || term.kind === "project")
+            return term.kind;
+        return `${term.kind}:${term.id}`;
+    }
+    /*  resolve the configuration filename based on the selected scope term  */
+    resolveFilename(name, term) {
+        if (term.kind === "default")
+            throw new Error("internal error: \"default\" scope has no filename");
+        if (term.kind === "user")
+            return path.join(userConfigDir(), `${name}.yaml`);
+        else if (term.kind === "project") {
+            const rel = path.join(".ase", `${name}.yaml`);
+            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 root = projectRoot() ?? process.cwd();
+            return path.join(root, ".ase", "task", term.id, `${name}.yaml`);
+        }
+        else
+            return path.join(userStateDir(), "session", term.id, `${name}.yaml`);
+    }
+    /*  upward-walk on filesystem for a file path relative to a start directory,
+        bounded above (inclusive) by a stop directory  */
+    findUpward(start, stop, rel) {
+        let dir = fs.realpathSync(start);
+        const end = fs.realpathSync(stop);
+        const steps = dir.split(path.sep).length - end.split(path.sep).length;
+        if (steps < 0)
+            return null;
+        for (let i = 0; i <= steps; i++) {
+            const candidate = path.join(dir, rel);
+            if (fs.existsSync(candidate))
+                return candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+        return null;
+    }
+    /*  read the full scope chain into memory; the requested mode applies
+        to the target scope only, inherited scopes are always lenient  */
+    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") {
+                const doc = new Document();
+                doc.contents = doc.createNode({});
+                if (this.name === "config") {
+                    const preset = projectClassificationPresets.default;
+                    for (const [k, val] of Object.entries(preset)) {
+                        const segments = k.split(".");
+                        for (let j = 1; j < segments.length; j++) {
+                            const prefix = segments.slice(0, j);
+                            const node = doc.getIn(prefix, true);
+                            if (node === undefined)
+                                doc.setIn(prefix, doc.createNode({}));
+                        }
+                        doc.setIn(segments, doc.createNode(val));
+                    }
+                }
+                docs.push({ scope: sc, filename: "", doc });
+                continue;
+            }
+            const filename = this.resolveFilename(this.name, sc);
+            const isTarget = (i === chain.length - 1);
+            const perDocMode = isTarget ? mode : "lenient";
+            const text = fs.existsSync(filename) ? fs.readFileSync(filename, "utf8") : "";
+            let doc = parseDocument(text);
+            if (doc.errors.length > 0) {
+                const msg = `invalid YAML in ${filename}: ${doc.errors[0].message}`;
+                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();
+            }
+            else if (this.name === "config" && this.migrate(doc)) {
+                /*  persist the migration under the file lock (unless already held by us),
+                    re-reading the file there to not clobber a concurrent write  */
+                const persist = () => {
+                    const disk = parseDocument(fs.readFileSync(filename, "utf8"));
+                    if (disk.errors.length > 0 || !this.migrate(disk))
+                        return;
+                    const empty = isMap(disk.contents) && disk.contents.items.length === 0;
+                    writeFileAtomic.sync(filename, empty ? "" : disk.toString({ indent: 4 }), { encoding: "utf8", mode: this.fileMode(sc, disk) });
+                    this.log.write("info", `migrated obsolete configuration entries in ${filename}`);
+                };
+                try {
+                    if (this.locked === filename)
+                        persist();
+                    else {
+                        const release = lockfile.lockSync(filename);
+                        try {
+                            persist();
+                        }
+                        finally {
+                            release();
+                        }
+                    }
+                }
+                catch (err) {
+                    this.log.write("warning", `failed to migrate obsolete configuration entries in ${filename}: ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
+            }
+            docs.push({ scope: sc, filename, doc });
+        }
+        this.docs = docs;
+        this.target = docs.length - 1;
+        for (let i = 0; i < docs.length; i++) {
+            const isTarget = (i === this.target);
+            const perDocMode = isTarget ? mode : "lenient";
+            const removed = this.validateDoc(docs[i].doc, docs[i].filename, perDocMode);
+            if (isTarget)
+                this.pruned.push(...removed);
+        }
+    }
+    /*  migrate a configuration document in place from obsolete variables: the
+        (pre-1.1.0) "project.artifact.task.{basedir,files}", where "basedir" becomes
+        "project.task.store.url" (as "ase:<basedir>") unless the latter is already
+        set and "files" is dropped, and the (pre-1.1.0) "agent.{task,skill}", which
+        are dropped, as they moved into the internal session state;
+        returns whether the document was changed  */
+    migrate(doc) {
+        let changed = false;
+        const task = ["project", "artifact", "task"];
+        if (isMap(doc.getIn(task))) {
+            const basedir = doc.getIn([...task, "basedir"]);
+            const parent = doc.getIn(["project", "task"]);
+            const store = doc.getIn(["project", "task", "store"]);
+            if (typeof basedir === "string" && basedir !== ""
+                && (parent === undefined || isMap(parent)) && (store === undefined || isMap(store))
+                && !doc.hasIn(["project", "task", "store", "url"]))
+                doc.setIn(["project", "task", "store", "url"], `ase:${basedir}`);
+            doc.deleteIn(task);
+            changed = true;
+        }
+        if (isMap(doc.getIn(["agent"])))
+            for (const key of ["task", "skill"])
+                if (doc.deleteIn(["agent", key]))
+                    changed = true;
+        if (!changed)
+            return false;
+        for (const p of [["project", "artifact"], ["project"], ["agent"]]) {
+            const node = doc.getIn(p);
+            if (isMap(node) && node.items.length === 0)
+                doc.deleteIn(p);
+        }
+        return true;
+    }
+    /*  acquire a cross-process advisory lock on the target scope's file,
+        execute the callback, then release the lock  */
+    lock(cb) {
+        const td = this.docs[this.target];
+        if (td.scope.kind === "default")
+            throw new Error("internal error: \"default\" scope is not lockable");
+        fs.mkdirSync(path.dirname(td.filename), { recursive: true });
+        if (!fs.existsSync(td.filename))
+            fs.writeFileSync(td.filename, "", { encoding: "utf8", mode: this.fileMode(td.scope, null) });
+        const release = lockfile.lockSync(td.filename);
+        this.locked = td.filename;
+        try {
+            cb();
+        }
+        finally {
+            this.locked = null;
+            release();
+        }
+    }
+    /*  write in-memory configuration back to the target scope's file  */
+    write() {
+        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", mode: this.fileMode(td.scope, td.doc) });
+    }
+    /*  determine the file mode of a scope's file: user-private (0600) for the
+        user scope, the "store" files, and any file carrying secrets, else
+        undefined (which lets an existing file's mode be preserved)  */
+    fileMode(scope, doc) {
+        if (scope.kind === "user" || this.name === "store"
+            || (doc !== null && configSecretKeys.some((key) => doc.hasIn(key.split(".")))))
+            return 0o600;
+        return undefined;
+    }
+    /*  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 [];
+        const removed = [];
+        for (;;) {
+            const result = v.safeParse(this.schema, doc.toJS());
+            if (result.success)
+                return removed;
+            if (mode === "strict") {
+                const issues = result.issues.map((i) => {
+                    const dotPath = (i.path ?? []).map((p) => String(p.key)).join(".");
+                    return dotPath ? `${dotPath}: ${i.message}` : i.message;
+                }).join("; ");
+                throw new Error(`invalid configuration in ${filename}: ${issues}`);
+            }
+            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))
+                    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 (removed.length === before)
+                return removed;
+        }
+    }
+    /*  enumerate all full dotted leaf paths from the attached valibot schema  */
+    schemaLeafPaths() {
+        const unwrap = (s) => {
+            let cur = s;
+            while (cur !== undefined && cur !== null && (cur.type === "optional" || cur.type === "nullish"
+                || cur.type === "nullable" || cur.type === "undefinedable"))
+                cur = cur.wrapped;
+            return cur ?? null;
+        };
+        const walk = (s, prefix) => {
+            const u = unwrap(s);
+            if (u !== null
+                && (u.type === "object" || u.type === "strict_object" || u.type === "loose_object")
+                && u.entries !== undefined) {
+                const paths = [];
+                for (const [k, sub] of Object.entries(u.entries))
+                    paths.push(...walk(sub, [...prefix, k]));
+                return paths;
+            }
+            return [prefix];
+        };
+        return walk(this.schema, []);
+    }
+    /*  enumerate all full dotted keys known from the attached valibot schema  */
+    keys() {
+        if (this.schema === null)
+            return [];
+        return this.schemaLeafPaths().map((p) => p.join("."));
+    }
+    /*  resolve a (possibly trailing-segment) dotted key to its full schema path  */
+    resolveKey(key) {
+        if (this.schema === null)
+            return key;
+        const segs = key.split(".");
+        const matches = this.schemaLeafPaths().filter((p) => {
+            if (p.length < segs.length)
+                return false;
+            for (let i = 0; i < segs.length; i++)
+                if (p[p.length - segs.length + i] !== segs[i])
+                    return false;
+            return true;
+        });
+        if (matches.length === 0)
+            return key;
+        if (matches.length > 1)
+            throw new Error(`ambiguous key "${key}" matches: ${matches.map((m) => m.join(".")).join(", ")}`);
+        return matches[0].join(".");
+    }
+    /*  retrieve the effective value at a dotted key (strongest scope wins),
+        or the target scope's root contents if no key is given  */
+    get(key) {
+        if (key === undefined)
+            return this.docs[this.target].doc.contents;
+        return this.getScoped(key)?.value;
+    }
+    /*  retrieve the effective value at a dotted key (strongest scope wins)
+        together with the scope term and the configuration file (empty for
+        the built-in "default" scope) which supplied it  */
+    getScoped(key) {
+        const segs = this.resolveKey(key).split(".");
+        for (let i = this.docs.length - 1; i >= 0; i--) {
+            const node = this.docs[i].doc.getIn(segs);
+            if (node !== undefined)
+                return { value: node, scope: this.docs[i].scope, filename: this.docs[i].filename };
+        }
+        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() {
+        const keys = new Set();
+        const walk = (node, prefix) => {
+            if (isMap(node))
+                for (const item of node.items) {
+                    const k = [...prefix, String(item.key)];
+                    if (isMap(item.value))
+                        walk(item.value, k);
+                    else if (isScalar(item.value))
+                        keys.add(k.join("."));
+                    else
+                        throw new Error(`key "${k.join(".")}" has unsupported node type`);
+                }
+        };
+        for (const d of this.docs)
+            walk(d.doc.contents, []);
+        const result = [];
+        for (const k of keys) {
+            const segs = k.split(".");
+            for (let i = this.docs.length - 1; i >= 0; i--) {
+                const node = this.docs[i].doc.getIn(segs);
+                if (node !== undefined) {
+                    result.push({ key: k, value: node, scope: this.docs[i].scope });
+                    break;
+                }
+            }
+        }
+        result.sort((a, b) => a.key.localeCompare(b.key));
+        return result;
+    }
+    /*  determine whether a key is writable on a given scope kind  */
+    isWritableOn(key, kind) {
+        if (kind === "default")
+            return false;
+        const resolved = this.resolveKey(key);
+        const allowed = configWritableScopes[resolved] ?? configWritableScopesDefault;
+        return allowed.includes(kind);
+    }
+    /*  enforce write-scope policy for the current target scope  */
+    assertWritable(key) {
+        const td = this.docs[this.target];
+        const resolved = this.resolveKey(key);
+        const allowed = configWritableScopes[resolved] ?? configWritableScopesDefault;
+        if (!allowed.includes(td.scope.kind))
+            throw new Error(`cannot set "${resolved}" on scope "${Config.scopeLabel(td.scope)}": ` +
+                `this key is only writable on scope(s): ${allowed.join(", ")}`);
+    }
+    /*  set a value at a dotted key in the target scope, creating intermediate maps as needed  */
+    set(key, value) {
+        this.assertWritable(key);
+        const segments = this.resolveKey(key).split(".");
+        const td = this.docs[this.target];
+        const next = td.doc.clone();
+        for (let i = 1; i < segments.length; i++) {
+            const prefix = segments.slice(0, i);
+            const node = next.getIn(prefix, true);
+            if (node !== undefined && !isMap(node))
+                throw new Error(`cannot set "${key}": intermediate path "${prefix.join(".")}" is not a map`);
+            if (node === undefined)
+                next.setIn(prefix, next.createNode({}));
+        }
+        next.setIn(segments, value);
+        const saved = td.doc;
+        td.doc = next;
+        try {
+            this.validateDoc(td.doc, td.filename, "strict");
+        }
+        catch (err) {
+            td.doc = saved;
+            throw err;
+        }
+    }
+    /*  delete a value at a dotted key from the target scope  */
+    delete(key) {
+        this.assertWritable(key);
+        const td = this.docs[this.target];
+        if (td.doc.contents === null || td.doc.contents === undefined)
+            return;
+        const next = td.doc.clone();
+        next.deleteIn(this.resolveKey(key).split("."));
+        const saved = td.doc;
+        td.doc = next;
+        try {
+            this.validateDoc(td.doc, td.filename, "strict");
+        }
+        catch (err) {
+            td.doc = saved;
+            throw err;
+        }
+    }
+}
+/*  access the internal "state.yaml" of a session, which, unlike the
+    configuration, does not cascade through any weaker scope  */
+export const sessionState = (log, sessionId) => {
+    if (!/^[A-Za-z0-9._-]+$/.test(sessionId))
+        throw new Error(`invalid session id "${sessionId}"`);
+    return new Config("state", sessionStateSchema, log, [{ kind: "session", id: sessionId }]);
+};