@rse/ase 0.0.6 → 0.0.7

package/README.md

@@ -1,7 +1,7 @@
 
 $ npx @rse/ase init
-$ npx @rse/ase config agent.dev.llm.type=anthropic-claude-sonnet-4.5
-$ npx @rse/ase config agent.dev.llm.key=<foo>
+$ npx @rse/ase config agent.dev.llm.type anthropic-claude-sonnet-4.5
+$ npx @rse/ase config agent.dev.llm.key <foo>
 $ npx @rse/ase agent dev start
 
 Agents

package/dst/ase-agent-base.js

@@ -7,37 +7,28 @@
 export const createAgentCommandModule = (category, description, subCommands) => {
     /*  create sub-command handler  */
     const createSubCommandHandler = (subCommand) => {
-        return (argv) => {
-            if (argv.debug)
+        return (_opts, cmd) => {
+            const opts = cmd.optsWithGlobals();
+            if (opts.debug)
                 console.log(`DEBUG: agent ${category} ${subCommand} command`);
-            if (argv.verbose)
+            if (opts.verbose)
                 console.log(`VERBOSE: executing agent ${category} ${subCommand}...`);
             console.log(`Executing agent ${category} ${subCommand}...`);
             /*  TODO: implement agent ${category} sub-command logic  */
         };
     };
-    return {
-        command: `${category} <subcommand>`,
-        describe: `Execute ${description} agent operations`,
-        builder: (yargs) => {
-            let builder = yargs
-                .option("verbose", {
-                alias: "v",
-                type: "boolean",
-                describe: "Enable verbose output",
-                default: false
-            })
-                .demandCommand(1, `You need to specify a ${category} subcommand`);
-            /*  register all sub-commands  */
-            for (const subCmd of subCommands) {
-                builder = builder.command(subCmd, `Execute agent ${category} ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-            }
-            return builder;
-        },
-        handler: (argv) => {
-            /*  this handler is not called when sub-commands are used  */
-            if (argv.debug)
-                console.log(`DEBUG: agent ${category} command (no subcommand)`);
+    return (parent) => {
+        const agent = parent
+            .command(`${category}`)
+            .description(`Execute ${description} agent operations`)
+            .option("-v, --verbose", "Enable verbose output", false);
+        /*  register all sub-commands  */
+        for (const subCmd of subCommands) {
+            agent
+                .command(subCmd)
+                .description(`Execute agent ${category} ${subCmd} operation`)
+                .action(createSubCommandHandler(subCmd));
         }
+        return agent;
     };
 };

package/dst/ase-agent-biz.js

@@ -12,38 +12,29 @@ const bizSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent biz ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent biz ${subCommand}...`);
         console.log(`Executing agent biz ${subCommand}...`);
         /*  TODO: implement agent biz sub-command logic  */
     };
 };
-/*  create and export biz command module  */
-const bizCommand = {
-    command: "biz <subcommand>",
-    describe: "Execute business agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a biz subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of bizSubCommands) {
-            builder = builder.command(subCmd, `Execute agent biz ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent biz command (no subcommand)");
+/*  register biz command on the given parent  */
+const registerBizCommand = (parent) => {
+    const biz = parent
+        .command("biz")
+        .description("Execute business agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of bizSubCommands) {
+        biz
+            .command(subCmd)
+            .description(`Execute agent biz ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return biz;
 };
-export default bizCommand;
+export default registerBizCommand;

package/dst/ase-agent-dev.js

@@ -12,38 +12,29 @@ const devSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent dev ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent dev ${subCommand}...`);
         console.log(`Executing agent dev ${subCommand}...`);
         /*  TODO: implement agent dev sub-command logic  */
     };
 };
-/*  create and export dev command module  */
-const devCommand = {
-    command: "dev <subcommand>",
-    describe: "Execute development agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a dev subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of devSubCommands) {
-            builder = builder.command(subCmd, `Execute agent dev ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent dev command (no subcommand)");
+/*  register dev command on the given parent  */
+const registerDevCommand = (parent) => {
+    const dev = parent
+        .command("dev")
+        .description("Execute development agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of devSubCommands) {
+        dev
+            .command(subCmd)
+            .description(`Execute agent dev ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return dev;
 };
-export default devCommand;
+export default registerDevCommand;

package/dst/ase-agent-ops.js

@@ -12,38 +12,29 @@ const opsSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent ops ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent ops ${subCommand}...`);
         console.log(`Executing agent ops ${subCommand}...`);
         /*  TODO: implement agent ops sub-command logic  */
     };
 };
-/*  create and export ops command module  */
-const opsCommand = {
-    command: "ops <subcommand>",
-    describe: "Execute operations agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify an ops subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of opsSubCommands) {
-            builder = builder.command(subCmd, `Execute agent ops ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent ops command (no subcommand)");
+/*  register ops command on the given parent  */
+const registerOpsCommand = (parent) => {
+    const ops = parent
+        .command("ops")
+        .description("Execute operations agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of opsSubCommands) {
+        ops
+            .command(subCmd)
+            .description(`Execute agent ops ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return ops;
 };
-export default opsCommand;
+export default registerOpsCommand;

package/dst/ase-agent-prd.js

@@ -12,38 +12,29 @@ const prdSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent prd ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent prd ${subCommand}...`);
         console.log(`Executing agent prd ${subCommand}...`);
         /*  TODO: implement agent prd sub-command logic  */
     };
 };
-/*  create and export prd command module  */
-const prdCommand = {
-    command: "prd <subcommand>",
-    describe: "Execute production agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a prd subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of prdSubCommands) {
-            builder = builder.command(subCmd, `Execute agent prd ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent prd command (no subcommand)");
+/*  register prd command on the given parent  */
+const registerPrdCommand = (parent) => {
+    const prd = parent
+        .command("prd")
+        .description("Execute production agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of prdSubCommands) {
+        prd
+            .command(subCmd)
+            .description(`Execute agent prd ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return prd;
 };
-export default prdCommand;
+export default registerPrdCommand;

package/dst/ase-agent-prj.js

@@ -12,38 +12,29 @@ const prjSubCommands = [
 ];
 /*  create sub-command handler  */
 const createSubCommandHandler = (subCommand) => {
-    return (argv) => {
-        if (argv.debug)
+    return (_opts, cmd) => {
+        const opts = cmd.optsWithGlobals();
+        if (opts.debug)
             console.log(`DEBUG: agent prj ${subCommand} command`);
-        if (argv.verbose)
+        if (opts.verbose)
             console.log(`VERBOSE: executing agent prj ${subCommand}...`);
         console.log(`Executing agent prj ${subCommand}...`);
         /*  TODO: implement agent prj sub-command logic  */
     };
 };
-/*  create and export prj command module  */
-const prjCommand = {
-    command: "prj <subcommand>",
-    describe: "Execute project agent operations",
-    builder: (yargs) => {
-        let builder = yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .demandCommand(1, "You need to specify a prj subcommand");
-        /*  register all sub-commands  */
-        for (const subCmd of prjSubCommands) {
-            builder = builder.command(subCmd, `Execute agent prj ${subCmd} operation`, () => { }, createSubCommandHandler(subCmd));
-        }
-        return builder;
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent prj command (no subcommand)");
+/*  register prj command on the given parent  */
+const registerPrjCommand = (parent) => {
+    const prj = parent
+        .command("prj")
+        .description("Execute project agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all sub-commands  */
+    for (const subCmd of prjSubCommands) {
+        prj
+            .command(subCmd)
+            .description(`Execute agent prj ${subCmd} operation`)
+            .action(createSubCommandHandler(subCmd));
     }
+    return prj;
 };
-export default prjCommand;
+export default registerPrjCommand;

package/dst/ase-agent.js

@@ -3,33 +3,23 @@
 **  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 bizCommand from "./ase-agent-biz.js";
-import devCommand from "./ase-agent-dev.js";
-import opsCommand from "./ase-agent-ops.js";
-import prdCommand from "./ase-agent-prd.js";
-import prjCommand from "./ase-agent-prj.js";
-const agentCommand = {
-    command: "agent <subcommand>",
-    describe: "Execute agent operations",
-    builder: (yargs) => {
-        return yargs
-            .option("verbose", {
-            alias: "v",
-            type: "boolean",
-            describe: "Enable verbose output",
-            default: false
-        })
-            .command(bizCommand)
-            .command(devCommand)
-            .command(opsCommand)
-            .command(prdCommand)
-            .command(prjCommand)
-            .demandCommand(1, "You need to specify an agent subcommand");
-    },
-    handler: (argv) => {
-        /*  this handler is not called when sub-commands are used  */
-        if (argv.debug)
-            console.log("DEBUG: agent command (no subcommand)");
-    }
+import registerBizCommand from "./ase-agent-biz.js";
+import registerDevCommand from "./ase-agent-dev.js";
+import registerOpsCommand from "./ase-agent-ops.js";
+import registerPrdCommand from "./ase-agent-prd.js";
+import registerPrjCommand from "./ase-agent-prj.js";
+/*  register agent command on the given program  */
+const registerAgentCommand = (program) => {
+    const agent = program
+        .command("agent")
+        .description("Execute agent operations")
+        .option("-v, --verbose", "Enable verbose output", false);
+    /*  register all agent sub-commands  */
+    registerBizCommand(agent);
+    registerDevCommand(agent);
+    registerOpsCommand(agent);
+    registerPrdCommand(agent);
+    registerPrjCommand(agent);
+    return agent;
 };
-export default agentCommand;
+export default registerAgentCommand;

package/dst/ase-config.js

@@ -3,59 +3,186 @@
 **  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>)"
-        });
-    },
-    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  */
-            const list = (node, prefix) => {
-                if (isMap(node))
-                    for (const item of node.items) {
-                        const key = prefix ? `${prefix}.${item.key}` : String(item.key);
-                        if (isMap(item.value))
-                            list(item.value, key);
-                        else
-                            console.log(`${key} = ${isScalar(item.value) ? item.value.value : item.value}`);
-                    }
-            };
-            list(doc.contents, "");
+import { Document, parseDocument, isMap, isScalar } from "yaml";
+import { execaSync } from "execa";
+import * as v from "valibot";
+import Table from "cli-table3";
+/*  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)))
+    }))
+}));
+/*  encapsulate read/write access to a project-local ".ase/<name>.yaml" file  */
+export class Config {
+    filename;
+    doc;
+    schema;
+    constructor(name, schema) {
+        const rel = path.join(".ase", `${name}.yaml`);
+        const found = this.findUpward(process.cwd(), rel);
+        this.filename = found ?? path.join(this.gitToplevel() ?? process.cwd(), rel);
+        this.doc = new Document();
+        this.schema = schema ?? null;
+    }
+    /*  upward-walk on filesystem for a file path relative to a start directory  */
+    findUpward(start, rel) {
+        let dir = start;
+        for (;;) {
+            const candidate = path.join(dir, rel);
+            if (fs.existsSync(candidate))
+                return candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    /*  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;
         }
-        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({}));
+        catch {
+            return null;
+        }
+    }
+    /*  read configuration file into memory  */
+    read() {
+        const text = fs.existsSync(this.filename) ? fs.readFileSync(this.filename, "utf8") : "";
+        this.doc = parseDocument(text);
+        this.validate("lenient");
+    }
+    /*  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(".");
+                process.stderr.write(`ase: warning: invalid entry in ${this.filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}\n`);
+                if (segs.length > 0) {
+                    this.doc.deleteIn(segs);
+                    progressed = true;
+                }
             }
-            doc.setIn(segments, value);
-            fs.writeFileSync(filename, doc.toString(), "utf8");
+            if (!progressed)
+                return;
         }
-        else {
-            const value = doc.getIn(query.split("."));
-            console.log(value);
+    }
+    /*  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("."));
+    }
+    /*  set a value at a dotted key, creating intermediate maps as needed  */
+    set(key, value) {
+        const segments = key.split(".");
+        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({}));
         }
+        this.doc.setIn(segments, value);
+        this.validate("strict");
+    }
+    /*  delete a value at a dotted key  */
+    delete(key) {
+        this.doc.deleteIn(key.split("."));
     }
+}
+/*  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)]);
+                }
+        };
+        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 configCommand;
+export default registerConfigCommand;

package/dst/ase-service.js

@@ -7,9 +7,10 @@ import path from "node:path";
 import fs from "node:fs";
 import net from "node:net";
 import { spawn } from "node:child_process";
-import { parseDocument } from "yaml";
 import Hapi from "@hapi/hapi";
 import axios from "axios";
+import * as v from "valibot";
+import { Config, configSchema } from "./ase-config.js";
 const SERVE_ENV = "ASE_SERVICE_SERVE";
 const HOST = "127.0.0.1";
 const IDLE_MS = 30 * 60 * 1000;
@@ -17,56 +18,30 @@ const TICK_MS = 60 * 1000;
 const PORT_MIN = 42000;
 const PORT_MAX = 44000;
 const PORT_TRIES = 20;
-/*  upward-walk on filesystem for a file path relative to a start directory  */
-const findUpward = (start, rel) => {
-    let dir = start;
-    for (;;) {
-        const candidate = path.join(dir, rel);
-        if (fs.existsSync(candidate))
-            return candidate;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-};
+/*  schema for ".ase/service.yaml"  */
+const serviceSchema = v.nullish(v.strictObject({
+    port: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1024), v.maxValue(65535)))
+}));
 /*  load optional ".ase/config.yaml" and ".ase/service.yaml" files  */
 const loadContext = () => {
-    /*  find files  */
-    const cfgPath = findUpward(process.cwd(), ".ase/config.yaml");
-    const svcPath = findUpward(process.cwd(), ".ase/service.yaml");
+    /*  load files  */
+    const cfg = new Config("config", configSchema);
+    cfg.read();
+    const svc = new Config("service", serviceSchema);
+    svc.read();
     /*  determine project id  */
-    let projectId;
-    if (cfgPath !== null) {
-        const doc = parseDocument(fs.readFileSync(cfgPath, "utf8"));
-        projectId = doc.get("project-id");
-    }
-    if (projectId === undefined || projectId === null)
-        projectId = path.basename(process.cwd());
-    if (typeof projectId !== "string" || projectId.length === 0)
-        throw new Error(`invalid "project-id" in ${cfgPath ?? "<cwd basename>"}`);
+    const rawId = cfg.get("project.id");
+    const projectId = (rawId === undefined || rawId === null) ? path.basename(process.cwd()) : rawId;
     /*  determine service port  */
-    let port = null;
-    if (svcPath !== null) {
-        const doc = parseDocument(fs.readFileSync(svcPath, "utf8"));
-        const raw = doc.get("port");
-        if (raw !== undefined && raw !== null) {
-            if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1024 || raw > 65535)
-                throw new Error(`invalid "port" in ${svcPath} (expected integer 1024..65535)`);
-            port = raw;
-        }
-    }
+    const rawPort = svc.get("port");
+    const port = (rawPort === undefined || rawPort === null) ? null : rawPort;
     /*  determine path to ".ase" directory  */
-    const aseDir = cfgPath !== null ? path.dirname(cfgPath) :
-        svcPath !== null ? path.dirname(svcPath) :
-            path.join(process.cwd(), ".ase");
-    /*  determine path to final ".ase/service.yaml" file  */
-    const finalSvc = svcPath !== null ? svcPath : path.join(aseDir, "service.yaml");
+    const aseDir = path.dirname(svc.filename);
     /*  return context information  */
     return {
         projectId,
         port,
-        svcPath: finalSvc,
+        svc,
         aseDir
     };
 };
@@ -93,12 +68,9 @@ const allocatePort = async () => {
     throw new Error(`failed to allocate a port in ${PORT_MIN}..${PORT_MAX} after ${PORT_TRIES} attempts`);
 };
 /*  persist an allocated port into ".ase/service.yaml"  */
-const persistPort = (svcPath, port) => {
-    fs.mkdirSync(path.dirname(svcPath), { recursive: true });
-    const text = fs.existsSync(svcPath) ? fs.readFileSync(svcPath, "utf8") : "";
-    const doc = parseDocument(text);
-    doc.set("port", port);
-    fs.writeFileSync(svcPath, doc.toString(), "utf8");
+const persistPort = (svc, port) => {
+    svc.set("port", port);
+    svc.write();
 };
 /*  distinguish ECONNREFUSED from other Axios transport errors  */
 const isConnRefused = (err) => {
@@ -214,7 +186,7 @@ const doStart = async () => {
     let port = ctx.port;
     if (port === null) {
         port = await allocatePort();
-        persistPort(ctx.svcPath, port);
+        persistPort(ctx.svc, port);
     }
     if (process.env[SERVE_ENV] === "1") {
         await runService({ ...ctx, port });
@@ -227,16 +199,20 @@ const doStart = async () => {
     for (let i = 0; i < 50; i++) {
         await new Promise((resolve) => setTimeout(resolve, 100));
         const s = await probe(port);
-        if (s !== null && s >= 200 && s < 300)
+        if (s !== null && s >= 200 && s < 300) {
+            process.stdout.write(`ase: service: started on port ${port}\n`);
             return 0;
+        }
     }
     throw new Error("service failed to start within timeout");
 };
 /*  stop flow: no-op if no port configured or connection refused  */
 const doStop = async () => {
     const ctx = loadContext();
-    if (ctx.port === null)
+    if (ctx.port === null) {
+        process.stdout.write("ase: service: not running (no port configured)\n");
         return 0;
+    }
     try {
         const r = await axios.request({
             method: "GET",
@@ -247,17 +223,23 @@ const doStop = async () => {
         return r.status >= 200 && r.status < 300 ? 0 : 1;
     }
     catch (err) {
-        if (isConnRefused(err))
+        if (isConnRefused(err)) {
+            process.stdout.write(`ase: service: not running (port ${ctx.port} not responding)\n`);
             return 0;
+        }
         throw err;
     }
 };
 /*  passthrough flow: POST /command with the arbitrary cmd token  */
 const doPassthrough = async (cmd) => {
-    const ctx = loadContext();
-    if (ctx.port === null)
-        throw new Error("service not running (no port configured)");
-    try {
+    let ctx = loadContext();
+    if (ctx.port === null) {
+        await doStart();
+        ctx = loadContext();
+        if (ctx.port === null)
+            throw new Error("service not running (no port configured after auto-start)");
+    }
+    const send = async () => {
         const r = await axios.request({
             method: "POST",
             url: `http://${HOST}:${ctx.port}/command`,
@@ -273,37 +255,48 @@ const doPassthrough = async (cmd) => {
         if (!body.endsWith("\n"))
             process.stdout.write("\n");
         return r.status >= 200 && r.status < 300 ? 0 : 1;
+    };
+    try {
+        return await send();
     }
     catch (err) {
-        if (isConnRefused(err))
-            throw new Error("service not running (connection refused)");
+        if (isConnRefused(err)) {
+            await doStart();
+            return await send();
+        }
         throw err;
     }
 };
-/*  command-line handling  */
-const serviceCommand = {
-    command: "service",
-    describe: "Manage per-project background HTTP service",
-    builder: (yargs) => {
-        return yargs
-            .command("start", "Start the background service", {}, async () => {
-            process.exit(await doStart());
-        })
-            .command("stop", "Stop the background service", {}, async () => {
-            process.exit(await doStop());
-        })
-            .command("$0 <cmd>", "Send an arbitrary command to the service", (y) => {
-            return y.positional("cmd", {
-                type: "string",
-                describe: "Command token to dispatch"
-            });
-        }, async (argv) => {
-            process.exit(await doPassthrough(String(argv.cmd)));
-        })
-            .demandCommand(1, "You need to specify a service subcommand");
-    },
-    handler: () => {
-        /*  dispatched by nested subcommands  */
-    }
+/*  register CLI command "ase service"  */
+const registerServiceCommand = (program) => {
+    const service = program
+        .command("service")
+        .description("Manage per-project background HTTP service")
+        .action(() => {
+        service.outputHelp();
+        process.exit(1);
+    });
+    /*  register CLI sub-command "ase service start"  */
+    service
+        .command("start")
+        .description("Start the background service")
+        .action(async () => {
+        process.exit(await doStart());
+    });
+    /*  register CLI sub-command "ase service stop"  */
+    service
+        .command("stop")
+        .description("Stop the background service")
+        .action(async () => {
+        process.exit(await doStop());
+    });
+    /*  register CLI sub-command "ase service send"  */
+    service
+        .command("send")
+        .description("Send a command to the background service")
+        .argument("<cmd>", "Command token to dispatch to the service")
+        .action(async (cmd) => {
+        process.exit(await doPassthrough(cmd));
+    });
 };
-export default serviceCommand;
+export default registerServiceCommand;

package/dst/ase-setup.js

@@ -3,17 +3,16 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
-const setupCommand = {
-    command: "setup",
-    describe: "Setup ASE",
-    builder: (yargs) => {
-        return yargs;
-    },
-    handler: (argv) => {
-        if (argv.debug)
+const registerSetupCommand = (program) => {
+    program
+        .command("setup")
+        .description("Setup ASE")
+        .action((_opts, cmd) => {
+        const debug = Boolean(cmd.optsWithGlobals().debug);
+        if (debug)
             console.log("DEBUG: setup command");
         console.log("Setup ASE...");
         /*  TODO: implement setup logic  */
-    }
+    });
 };
-export default setupCommand;
+export default registerSetupCommand;

package/dst/ase.1

@@ -3,23 +3,59 @@
 \fBase\fR - Agentic Software Engineering (ASE)
 .SH "SYNOPSIS"
 .P
-\fBase\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fIcommand\fR \[lB]\fIoptions\fR \[lB]...\[rB]\[rB]\[rB] \[lB]\fIargs\fR \[lB]...\[rB]\[rB]\[rB]
+\fBase\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fB-d\fR|\fB--debug\fR\[rB] \[lB]\fIcommand\fR \[lB]\fIoptions\fR \[lB]...\[rB]\[rB] \[lB]\fIargs\fR \[lB]...\[rB]\[rB]\[rB]
 .SH "DESCRIPTION"
 .P
-\fBase\fR, \fIAgentic Software Engineeing (ASE)\fR, is a small command-line tool...
+\fBase\fR, \fIAgentic Software Engineering (ASE)\fR, is the command-line companion tool to the \fIASE\fR Claude Code plugin. It provides project-level configuration management and a small per-project background HTTP service for dispatching commands.
 .SH "OPTIONS"
 .P
-The following command-line options and arguments exist:
+The following top-level command-line options exist:
 .RS 0
 .IP \(bu 4
 \[lB]\fB-h\fR|\fB--help\fR\[rB]: Show program usage information only.
 .IP \(bu 4
 \[lB]\fB-V\fR|\fB--version\fR\[rB]: Show program version information only.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--debug\fR\[rB]: Enable debug output. The flag is inherited by all subcommands and can be inspected inside handlers via \fBcmd.optsWithGlobals()\fR.
+.RE 0
+
+.SH "COMMANDS"
+.P
+The following top-level commands exist:
+.RS 0
+.IP \(bu 4
+\fBase config\fR: Manage \fIASE\fR configuration stored in \fB.ase/config.yaml\fR. Without a subcommand, prints usage information. The file is validated against a schema: on read, unknown or invalid entries are warned about and silently dropped from the in-memory view; on set/write, they cause a fatal error.
+.IP \(bu 4
+\fBase config get\fR \fIkey\fR: Print the value at the given dotted \fIkey\fR. Fails with an error if \fIkey\fR does not resolve to a leaf value.
+.IP \(bu 4
+\fBase config set\fR \fIkey\fR \fIvalue\fR: Set the value at the given dotted \fIkey\fR (creating intermediate maps as needed) and persist the file.
+.IP \(bu 4
+\fBase config list\fR: List all configured values as flat dotted keys, rendered as a two-column table of \fBkey\fR and \fBvalue\fR.
+.IP \(bu 4
+\fBase config edit\fR: Open \fB.ase/config.yaml\fR in the editor defined by the \fB$EDITOR\fR or \fB$VISUAL\fR environment variable (falling back to \fBvi\fR). The file and its parent directory are created if missing. After the editor exits, the file is re-read and schema warnings are reported.
+.IP \(bu 4
+\fBase service\fR: Manage the per-project background HTTP service. The service is bound to \fB127.0.0.1\fR on a port persisted in \fB.ase/service.yaml\fR and stops itself after 30 minutes of idle time. Without a subcommand, the help text is shown.
+.IP \(bu 4
+\fBase service start\fR: Start the background service (detached). Allocates a random port in the range \fB42000\fR..\fB44000\fR if none is persisted yet, writes it to \fB.ase/service.yaml\fR, and probes readiness. Exits silently with status 0 if the service is already running; prints \fBase: service: started on port <port>\fR on a fresh start.
+.IP \(bu 4
+\fBase service stop\fR: Stop the background service via HTTP \fBGET /stop\fR. Exits silently with status 0 on successful stop. If no port is configured or the port is not responding, prints an informational message and exits with status 0.
+.IP \(bu 4
+\fBase service send\fR \fIcmd\fR: Dispatch the \fIcmd\fR token as a passthrough command to the running service via HTTP \fBPOST /command\fR; if the service is not running, it is auto-started first.
+.RE 0
+
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/config.yaml\fR: Per-project \fIASE\fR configuration. Read upward from the current working directory. Recognized key: \fBproject.id\fR (non-empty string).
+.IP \(bu 4
+\fB.ase/service.yaml\fR: Per-project service state. Recognized key: \fBport\fR (integer in \fB1024\fR..\fB65535\fR).
+.IP \(bu 4
+\fB.ase/service.log\fR: Stdout/stderr log of the detached background service.
 .RE 0
 
 .SH "HISTORY"
 .P
-\fBase\fR was started to be developed in October 2025...
+\fBase\fR was started to be developed in October 2025.
 .SH "AUTHOR"
 .P
 Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/ase.js

@@ -4,39 +4,35 @@
 **  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 yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import configCommand from "./ase-config.js";
-import setupCommand from "./ase-setup.js";
-import serviceCommand from "./ase-service.js";
+import { Command, CommanderError } from "commander";
+import registerConfigCommand from "./ase-config.js";
+import registerServiceCommand from "./ase-service.js";
 /*  parse CLI arguments  */
 try {
-    await yargs(hideBin(process.argv))
-        .scriptName("ase")
-        .usage("Usage: $0 <command> [options]")
-        .option("debug", {
-        alias: "d",
-        type: "boolean",
-        describe: "Enable debug output",
-        default: false
-    })
-        .command(configCommand)
-        .command(setupCommand)
-        .command(serviceCommand)
-        .demandCommand(1, "You need to specify a command")
-        .fail((msg, err, yargs) => {
-        if (err)
-            throw err;
-        yargs.showHelp();
-        process.stderr.write(`\nase: ${msg}\n`);
-        process.exit(1);
-    })
-        .help()
-        .version()
-        .strict()
-        .parseAsync();
+    /*  establish top-level program  */
+    const program = new Command();
+    program
+        .name("ase")
+        .usage("<command> [options]")
+        .option("-d, --debug", "enable debug output", false)
+        .showHelpAfterError()
+        .enablePositionalOptions()
+        .exitOverride();
+    /*  register top-level commands  */
+    registerConfigCommand(program);
+    registerServiceCommand(program);
+    /*  parse program arguments  */
+    await program.parseAsync(process.argv);
+    /*  gracefully terminate  */
+    process.exit(0);
 }
 catch (err) {
+    if (err instanceof CommanderError) {
+        if (err.exitCode !== 0)
+            process.exit(err.exitCode);
+        else
+            process.exit(0);
+    }
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`ase: ERROR: ${message}\n`);
     process.exit(1);

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.6",
+    "version":                              "0.0.7",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -34,16 +34,17 @@
         "remark":                           "15.0.1",
         "remark-man":                       "9.0.0",
 
-        "@types/node":                      "25.6.0",
-        "@types/yargs":                     "17.0.35"
+        "@types/node":                      "25.6.0"
     },
     "dependencies": {
-        "yargs":                            "18.0.0",
+        "commander":                        "14.0.3",
         "yaml":                             "2.8.3",
+        "valibot":                          "1.3.1",
         "execa":                            "9.6.1",
         "mkdirp":                           "3.0.1",
         "@hapi/hapi":                       "21.4.8",
-        "axios":                            "1.15.0"
+        "axios":                            "1.15.0",
+        "cli-table3":                       "0.6.5"
     },
     "engines": {
         "npm":                              ">=10.0.0",