@rse/ase 0.0.7 → 0.0.8

package/dst/ase-config.js

@@ -5,14 +5,86 @@
 */
 import path from "node:path";
 import fs from "node:fs";
+import readline from "node:readline/promises";
 import { Document, parseDocument, isMap, isScalar } from "yaml";
 import { execaSync } from "execa";
 import * as v from "valibot";
 import Table from "cli-table3";
+/*  classification taxonomy  */
+export const projectClassification = {
+    source: {
+        ambition: ["artist", "craftsman", "engineer"],
+        boxing: ["white", "grey", "black"],
+        size: ["small", "medium", "large"],
+        structure: ["bare", "library", "framework"]
+    },
+    process: {
+        actors: ["person", "team", "crew"],
+        control: ["human", "hitl", "agent"],
+        drive: ["spec", "code", "test"]
+    },
+    result: {
+        target: ["prototype", "mvp", "product"]
+    }
+};
+/*  classification presets  */
+export const projectClassificationPresets = {
+    vibe: {
+        "project.id": "example",
+        "project.name": "Example Project",
+        "project.source.ambition": "engineer",
+        "project.source.boxing": "black",
+        "project.source.size": "small",
+        "project.source.structure": "bare",
+        "project.process.actors": "person",
+        "project.process.control": "agent",
+        "project.process.drive": "spec",
+        "project.result.target": "prototype"
+    },
+    pro: {
+        "project.id": "example",
+        "project.name": "Example Project",
+        "project.source.ambition": "artist",
+        "project.source.boxing": "white",
+        "project.source.size": "medium",
+        "project.source.structure": "framework",
+        "project.process.actors": "person",
+        "project.process.control": "human",
+        "project.process.drive": "code",
+        "project.result.target": "product"
+    },
+    industry: {
+        "project.id": "example",
+        "project.name": "Example Project",
+        "project.source.ambition": "craftsman",
+        "project.source.boxing": "grey",
+        "project.source.size": "large",
+        "project.source.structure": "framework",
+        "project.process.actors": "crew",
+        "project.process.control": "hitl",
+        "project.process.drive": "code",
+        "project.result.target": "mvp"
+    }
+};
 /*  schema for ".ase/config.yaml"  */
 export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
-        id: v.optional(v.pipe(v.string(), v.minLength(1)))
+        id: v.optional(v.pipe(v.string(), v.minLength(1))),
+        name: v.optional(v.pipe(v.string(), v.minLength(1))),
+        source: v.optional(v.strictObject({
+            ambition: v.optional(v.picklist(projectClassification.source.ambition)),
+            boxing: v.optional(v.picklist(projectClassification.source.boxing)),
+            size: v.optional(v.picklist(projectClassification.source.size)),
+            structure: v.optional(v.picklist(projectClassification.source.structure))
+        })),
+        process: v.optional(v.strictObject({
+            actors: v.optional(v.picklist(projectClassification.process.actors)),
+            control: v.optional(v.picklist(projectClassification.process.control)),
+            drive: v.optional(v.picklist(projectClassification.process.drive))
+        })),
+        result: v.optional(v.strictObject({
+            target: v.optional(v.picklist(projectClassification.result.target))
+        }))
     }))
 }));
 /*  encapsulate read/write access to a project-local ".ase/<name>.yaml" file  */
@@ -20,17 +92,27 @@ export class Config {
     filename;
     doc;
     schema;
-    constructor(name, schema) {
+    log;
+    constructor(name, schema, log) {
         const rel = path.join(".ase", `${name}.yaml`);
-        const found = this.findUpward(process.cwd(), rel);
-        this.filename = found ?? path.join(this.gitToplevel() ?? process.cwd(), rel);
+        const cwd = process.cwd();
+        const top = this.gitToplevel();
+        const found = top !== null ?
+            this.findUpward(cwd, top, rel) :
+            (fs.existsSync(path.join(cwd, rel)) ? path.join(cwd, rel) : null);
+        this.filename = found ?? path.join(top ?? cwd, rel);
         this.doc = new Document();
         this.schema = schema ?? null;
+        this.log = log;
     }
-    /*  upward-walk on filesystem for a file path relative to a start directory  */
-    findUpward(start, rel) {
-        let dir = start;
-        for (;;) {
+    /*  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 between = path.relative(end, dir);
+        const steps = between === "" ? 0 : between.split(path.sep).length;
+        for (let i = 0; i <= steps; i++) {
             const candidate = path.join(dir, rel);
             if (fs.existsSync(candidate))
                 return candidate;
@@ -39,6 +121,7 @@ export class Config {
                 return null;
             dir = parent;
         }
+        return null;
     }
     /*  determine the Git top-level directory, if inside a Git repository  */
     gitToplevel() {
@@ -53,10 +136,17 @@ export class Config {
         }
     }
     /*  read configuration file into memory  */
-    read() {
+    read(mode = "lenient") {
         const text = fs.existsSync(this.filename) ? fs.readFileSync(this.filename, "utf8") : "";
         this.doc = parseDocument(text);
-        this.validate("lenient");
+        if (this.doc.errors.length > 0) {
+            const msg = `invalid YAML in ${this.filename}: ${this.doc.errors[0].message}`;
+            if (mode === "strict")
+                throw new Error(msg);
+            this.log.write("warning", msg);
+            this.doc = new Document();
+        }
+        this.validate(mode);
     }
     /*  write in-memory configuration back to file  */
     write() {
@@ -83,106 +173,220 @@ export class Config {
             for (const i of result.issues) {
                 const segs = (i.path ?? []).map((p) => String(p.key));
                 const dotPath = segs.join(".");
-                process.stderr.write(`ase: warning: invalid entry in ${this.filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}\n`);
+                this.log.write("warning", `invalid entry in ${this.filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}`);
                 if (segs.length > 0) {
                     this.doc.deleteIn(segs);
                     progressed = true;
                 }
+                else
+                    /*  root-level issue is structurally unrecoverable: do not wipe
+                        the document, let the next strict validate() surface it  */
+                    return;
             }
             if (!progressed)
                 return;
         }
     }
+    /*  enumerate all full dotted leaf paths from the attached valibot schema  */
+    schemaLeafPaths() {
+        const unwrap = (s) => {
+            while (s !== undefined && s !== null && (s.type === "optional" || s.type === "nullish"
+                || s.type === "nullable" || s.type === "undefinedable"))
+                s = s.wrapped;
+            return s;
+        };
+        const walk = (s, prefix) => {
+            const u = unwrap(s);
+            if (u !== undefined && 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, []);
+    }
+    /*  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 a value at a dotted key, or the root contents if no key given  */
     get(key) {
         if (key === undefined)
             return this.doc.contents;
-        return this.doc.getIn(key.split("."));
+        return this.doc.getIn(this.resolveKey(key).split("."));
     }
     /*  set a value at a dotted key, creating intermediate maps as needed  */
     set(key, value) {
-        const segments = key.split(".");
+        const segments = this.resolveKey(key).split(".");
+        const next = this.doc.clone();
         for (let i = 1; i < segments.length; i++) {
             const prefix = segments.slice(0, i);
-            const node = this.doc.getIn(prefix, true);
-            if (!isMap(node))
-                this.doc.setIn(prefix, this.doc.createNode({}));
+            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 = this.doc;
+        this.doc = next;
+        try {
+            this.validate("strict");
+        }
+        catch (err) {
+            this.doc = saved;
+            throw err;
         }
-        this.doc.setIn(segments, value);
-        this.validate("strict");
     }
     /*  delete a value at a dotted key  */
     delete(key) {
-        this.doc.deleteIn(key.split("."));
+        const next = this.doc.clone();
+        next.deleteIn(this.resolveKey(key).split("."));
+        const saved = this.doc;
+        this.doc = next;
+        try {
+            this.validate("strict");
+        }
+        catch (err) {
+            this.doc = saved;
+            throw err;
+        }
     }
 }
-/*  register CLI command "ase config"  */
-const registerConfigCommand = (program) => {
-    const configCmd = program
-        .command("config")
-        .description("Manage ASE configuration")
-        .action((_opts, cmd) => {
-        cmd.help();
-    });
-    /*  register CLI sub-command "ase config get"  */
-    configCmd
-        .command("get")
-        .description("Print the value at a dotted configuration key")
-        .argument("<key>", "Configuration key (dotted path)")
-        .action((key) => {
-        const cfg = new Config("config", configSchema);
-        cfg.read();
-        const v = cfg.get(key);
-        if (isMap(v))
-            throw new Error(`key "${key}" is not a leaf key`);
-        console.log(isScalar(v) ? v.value : v);
-    });
-    /*  register CLI sub-command "ase config set"  */
-    configCmd
-        .command("set")
-        .description("Set the value at a dotted configuration key")
-        .argument("<key>", "Configuration key (dotted path)")
-        .argument("<value>", "Configuration value")
-        .action((key, value) => {
-        const cfg = new Config("config", configSchema);
-        cfg.read();
-        console.log(`${key}: ${value}`);
-        cfg.set(key, value);
-        cfg.write();
-    });
-    /*  register CLI sub-command "ase config list"  */
-    configCmd
-        .command("list")
-        .description("List all configured values as flat dotted keys")
-        .action(() => {
-        const cfg = new Config("config", configSchema);
-        cfg.read();
-        const table = new Table({ head: ["key", "value"] });
-        const list = (node, prefix) => {
-            if (isMap(node))
-                for (const item of node.items) {
-                    const k = prefix ? `${prefix}.${item.key}` : String(item.key);
-                    if (isMap(item.value))
-                        list(item.value, k);
-                    else
-                        table.push([k, String(isScalar(item.value) ? item.value.value : item.value)]);
+/*  CLI command "ase config"  */
+export default class ConfigCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase config"  */
+        const configCmd = program
+            .command("config")
+            .description("Manage ASE configuration")
+            .action((_opts, cmd) => {
+            cmd.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase config init"  */
+        configCmd
+            .command("init")
+            .description("Initialize configuration with preset values (vibe|pro|industry)")
+            .argument("<type>", "Preset type (vibe|pro|industry)")
+            .action((type) => {
+            const preset = projectClassificationPresets[type];
+            if (preset === undefined)
+                throw new Error(`unknown preset "${type}" (expected: vibe|pro|industry)`);
+            const cfg = new Config("config", configSchema, this.log);
+            cfg.read();
+            for (const [k, val] of Object.entries(preset))
+                cfg.set(k, val);
+            cfg.write();
+        });
+        /*  register CLI sub-command "ase config list"  */
+        configCmd
+            .command("list")
+            .description("List all configured values as flat dotted keys")
+            .action(() => {
+            const cfg = new Config("config", configSchema, this.log);
+            cfg.read();
+            const table = new Table({
+                head: ["KEY", "VALUE"],
+                chars: { "mid": "", "left-mid": "", "mid-mid": "", "right-mid": "" },
+                style: { head: ["blue"] }
+            });
+            const list = (node, prefix) => {
+                if (isMap(node))
+                    for (const item of node.items) {
+                        const k = prefix ? `${prefix}.${item.key}` : String(item.key);
+                        if (isMap(item.value))
+                            list(item.value, k);
+                        else if (!isScalar(item.value))
+                            throw new Error(`key "${k}" has unsupported node type`);
+                        else
+                            table.push([k, String(item.value.value)]);
+                    }
+            };
+            list(cfg.get(), "");
+            process.stdout.write(`${table.toString()}\n`);
+        });
+        /*  register CLI sub-command "ase config edit"  */
+        configCmd
+            .command("edit")
+            .description("Edit configuration file with $EDITOR")
+            .action(async () => {
+            const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+            const cfg = new Config("config", configSchema, this.log);
+            fs.mkdirSync(path.dirname(cfg.filename), { recursive: true });
+            if (!fs.existsSync(cfg.filename))
+                fs.writeFileSync(cfg.filename, "", "utf8");
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                for (;;) {
+                    execaSync(editor, [cfg.filename], { stdio: "inherit" });
+                    try {
+                        cfg.read("strict");
+                        break;
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        this.log.write("error", msg);
+                        const ans = (await rl.question("re-edit? [Y/n] ")).trim().toLowerCase();
+                        if (ans === "n" || ans === "no")
+                            throw err;
+                    }
                 }
-        };
-        list(cfg.get(), "");
-        console.log(table.toString());
-    });
-    /*  register CLI sub-command "ase config edit"  */
-    configCmd
-        .command("edit")
-        .description("Edit configuration file with $EDITOR")
-        .action(() => {
-        const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
-        const cfg = new Config("config", configSchema);
-        fs.mkdirSync(path.dirname(cfg.filename), { recursive: true });
-        if (!fs.existsSync(cfg.filename))
-            fs.writeFileSync(cfg.filename, "", "utf8");
-        execaSync(editor, [cfg.filename], { stdio: "inherit" });
-        cfg.read();
-    });
-};
-export default registerConfigCommand;
+            }
+            finally {
+                rl.close();
+            }
+        });
+        /*  register CLI sub-command "ase config get"  */
+        configCmd
+            .command("get")
+            .description("Print the value at a dotted configuration key")
+            .argument("<key>", "Configuration key (dotted path)")
+            .action((key) => {
+            const cfg = new Config("config", configSchema, this.log);
+            cfg.read();
+            const val = cfg.get(key);
+            if (val === undefined)
+                throw new Error(`key "${key}" is not set`);
+            if (isMap(val))
+                throw new Error(`key "${key}" is not a leaf key`);
+            process.stdout.write(`${isScalar(val) ? val.value : val}\n`);
+        });
+        /*  register CLI sub-command "ase config set"  */
+        configCmd
+            .command("set")
+            .description("Set the value at a dotted configuration key")
+            .argument("<key>", "Configuration key (dotted path)")
+            .argument("<value>", "Configuration value")
+            .action((key, value) => {
+            const cfg = new Config("config", configSchema, this.log);
+            cfg.read();
+            cfg.set(key, value);
+            cfg.write();
+        });
+    }
+}

package/dst/ase-log.js

@@ -0,0 +1,69 @@
+/*
+**  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 fs from "node:fs";
+import chalk from "chalk";
+import { DateTime } from "luxon";
+const levels = [
+    { name: "error", style: chalk.red.bold },
+    { name: "warning", style: chalk.yellow.bold },
+    { name: "info", style: chalk.blue },
+    { name: "debug", style: chalk.green }
+];
+export default class Log {
+    _program;
+    _logLevel;
+    _logFile;
+    stream = null;
+    logLevelIdx = 0;
+    constructor(_program, _logLevel, _logFile) {
+        this._program = _program;
+        this._logLevel = _logLevel;
+        this._logFile = _logFile;
+    }
+    async init() {
+        /*  log messages  */
+        const idx = levels.findIndex((l) => l.name === this._logLevel);
+        if (idx === -1)
+            throw new RangeError(`invalid log level "${this._logLevel}" (expected one of: ${levels.map((l) => l.name).join(", ")})`);
+        this.logLevelIdx = idx;
+        if (this._logFile !== "-")
+            this.stream = fs.createWriteStream(this._logFile, { flags: "a", encoding: "utf8" });
+    }
+    logLevel(level) {
+        const idx = levels.findIndex((l) => l.name === level);
+        if (idx === -1)
+            throw new RangeError(`invalid log level "${level}" (expected one of: ${levels.map((l) => l.name).join(", ")})`);
+        this._logLevel = level;
+        this.logLevelIdx = idx;
+    }
+    logFile(file) {
+        if (file === this._logFile)
+            return;
+        this._logFile = file;
+        if (this.stream !== null) {
+            this.stream.end();
+            this.stream = null;
+        }
+        if (file !== "-")
+            this.stream = fs.createWriteStream(file, { flags: "a", encoding: "utf8" });
+    }
+    write(level, msg) {
+        const idx = levels.findIndex((l) => l.name === level);
+        if (idx !== -1 && idx <= this.logLevelIdx) {
+            const timestamp = DateTime.now().toFormat("yyyy-LL-dd HH:mm:ss.SSS");
+            let line = `${this._program}: [${timestamp}]: `;
+            if (this._logFile === "-" && process.stdout.isTTY)
+                line += `${levels[idx].style("[" + levels[idx].name.toUpperCase() + "]")}`;
+            else
+                line += `[${levels[idx].name.toUpperCase()}]`;
+            line += `: ${msg}\n`;
+            if (this._logFile === "-")
+                process.stdout.write(line);
+            else if (this.stream !== null)
+                this.stream.write(line);
+        }
+    }
+}