@rse/ase 0.0.6 → 0.0.8

package/dst/ase-config.js

@@ -3,59 +3,390 @@
 **  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 os from "node:os";
 import path from "node:path";
 import fs from "node:fs";
-import { parseDocument, isMap, isScalar } from "yaml";
-const configCommand = {
-    command: "config [query]",
-    describe: "Manage ASE configuration",
-    builder: (yargs) => {
-        return yargs
-            .positional("query", {
-            type: "string",
-            describe: "Configuration query (none, <key>, or <key>=<value>)"
-        });
+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"
     },
-    handler: (argv) => {
-        if (argv.debug)
-            console.log("DEBUG: config command", argv);
-        const query = argv.query;
-        const filename = path.join(os.homedir(), ".ase.yaml");
-        const text = fs.existsSync(filename) ? fs.readFileSync(filename, "utf8") : "";
-        const doc = parseDocument(text);
-        if (!query) {
-            /*  list all values as flat dotted keys  */
+    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))),
+        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  */
+export class Config {
+    filename;
+    doc;
+    schema;
+    log;
+    constructor(name, schema, log) {
+        const rel = path.join(".ase", `${name}.yaml`);
+        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,
+        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;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+        return null;
+    }
+    /*  determine the Git top-level directory, if inside a Git repository  */
+    gitToplevel() {
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
+                stderr: "ignore"
+            });
+            return result.stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /*  read configuration file into memory  */
+    read(mode = "lenient") {
+        const text = fs.existsSync(this.filename) ? fs.readFileSync(this.filename, "utf8") : "";
+        this.doc = parseDocument(text);
+        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() {
+        this.validate("strict");
+        fs.mkdirSync(path.dirname(this.filename), { recursive: true });
+        fs.writeFileSync(this.filename, this.doc.toString({ indent: 4 }), "utf8");
+    }
+    /*  validate in-memory configuration against the optional schema  */
+    validate(mode = "strict") {
+        if (this.schema === null)
+            return;
+        for (;;) {
+            const result = v.safeParse(this.schema, this.doc.toJS());
+            if (result.success)
+                return;
+            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 ${this.filename}: ${issues}`);
+            }
+            let progressed = false;
+            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 ${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(this.resolveKey(key).split("."));
+    }
+    /*  set a value at a dotted key, creating intermediate maps as needed  */
+    set(key, value) {
+        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 = 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;
+        }
+    }
+    /*  delete a value at a dotted key  */
+    delete(key) {
+        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;
+        }
+    }
+}
+/*  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 key = prefix ? `${prefix}.${item.key}` : String(item.key);
+                        const k = prefix ? `${prefix}.${item.key}` : String(item.key);
                         if (isMap(item.value))
-                            list(item.value, key);
+                            list(item.value, k);
+                        else if (!isScalar(item.value))
+                            throw new Error(`key "${k}" has unsupported node type`);
                         else
-                            console.log(`${key} = ${isScalar(item.value) ? item.value.value : item.value}`);
+                            table.push([k, String(item.value.value)]);
                     }
             };
-            list(doc.contents, "");
-        }
-        else if (query.includes("=")) {
-            const [key, ...valueParts] = query.split("=");
-            const value = valueParts.join("=");
-            console.log(`Setting configuration: ${key} = ${value}`);
-            const segments = key.split(".");
-            for (let i = 1; i < segments.length; i++) {
-                const prefix = segments.slice(0, i);
-                const node = doc.getIn(prefix, true);
-                if (!isMap(node))
-                    doc.setIn(prefix, doc.createNode({}));
+            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;
+                    }
+                }
             }
-            doc.setIn(segments, value);
-            fs.writeFileSync(filename, doc.toString(), "utf8");
-        }
-        else {
-            const value = doc.getIn(query.split("."));
-            console.log(value);
-        }
+            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();
+        });
     }
-};
-export default configCommand;
+}

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);
+        }
+    }
+}