@rse/ase 0.0.4 → 0.0.6

package/dst/ase-config.js

@@ -3,33 +3,58 @@
 **  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 [assignment]",
+    command: "config [query]",
     describe: "Manage ASE configuration",
     builder: (yargs) => {
         return yargs
-            .positional("assignment", {
+            .positional("query", {
             type: "string",
-            describe: "Configuration assignment (key=value) or key to query"
+            describe: "Configuration query (none, <key>, or <key>=<value>)"
         });
     },
     handler: (argv) => {
         if (argv.debug)
             console.log("DEBUG: config command", argv);
-        const assignment = argv.assignment;
-        if (!assignment) {
-            console.log("Listing all configuration...");
-            /*  TODO: implement configuration listing logic  */
+        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, "");
         }
-        else if (assignment.includes("=")) {
-            const [key, ...valueParts] = assignment.split("=");
+        else if (query.includes("=")) {
+            const [key, ...valueParts] = query.split("=");
             const value = valueParts.join("=");
             console.log(`Setting configuration: ${key} = ${value}`);
-            /*  TODO: implement configuration storage logic  */
+            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({}));
+            }
+            doc.setIn(segments, value);
+            fs.writeFileSync(filename, doc.toString(), "utf8");
         }
         else {
-            console.log(`Getting configuration: ${assignment}`);
-            /*  TODO: implement configuration retrieval logic  */
+            const value = doc.getIn(query.split("."));
+            console.log(value);
         }
     }
 };

package/dst/ase-meta-plan.js

@@ -0,0 +1,78 @@
+/*
+**  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 path from "node:path";
+import fs from "node:fs";
+import { execa } from "execa";
+import { mkdirp } from "mkdirp";
+const configCommand = {
+    command: "meta-plan <subcommand>",
+    describe: "Manage plans",
+    builder: (yargs) => {
+        return yargs
+            .command({
+            command: "init",
+            describe: "ensure plan directory exists",
+            handler: async () => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+            }
+        })
+            .command({
+            command: "load <id>",
+            describe: "load a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.existsSync(planFile) ? fs.readFileSync(planFile, "utf8") : "";
+                process.stdout.write(text);
+            }
+        })
+            .command({
+            command: "save <id>",
+            describe: "save a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.readFileSync(0, "utf8");
+                fs.writeFileSync(planFile, text);
+            }
+        })
+            .command({
+            command: "edit <id>",
+            describe: "edit a plan interactively with $EDITOR",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const editor = process.env.EDITOR ?? "vi";
+                await execa(editor, [planFile], { stdio: "inherit" });
+            }
+        })
+            .demandCommand(1, "You need to specify a sub-command");
+    },
+    handler: () => { }
+};
+export default configCommand;

package/dst/ase-plan.js

@@ -0,0 +1,82 @@
+/*
+**  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 path from "node:path";
+import fs from "node:fs";
+import { execa } from "execa";
+import { mkdirp } from "mkdirp";
+const planCommand = {
+    command: "plan <subcommand>",
+    describe: "Manage plans",
+    builder: (yargs) => {
+        return yargs
+            .command({
+            command: "ensure",
+            describe: "ensure plan directory exists",
+            handler: async () => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                process.stdout.write(planDir);
+            }
+        })
+            .command({
+            command: "load <id>",
+            describe: "load a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const text = fs.existsSync(planFile) ? fs.readFileSync(planFile, "utf8") : "";
+                process.stdout.write(text);
+            }
+        })
+            .command({
+            command: "save <id>",
+            describe: "save a plan",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                const chunks = [];
+                for await (const chunk of process.stdin)
+                    chunks.push(chunk);
+                const text = Buffer.concat(chunks).toString("utf8");
+                fs.writeFileSync(planFile, text);
+            }
+        })
+            .command({
+            command: "edit <id>",
+            describe: "edit a plan interactively with $EDITOR",
+            builder: (yargs) => yargs.positional("id", {
+                type: "string",
+                describe: "plan identifier"
+            }),
+            handler: async (argv) => {
+                const { stdout: root } = await execa("git", ["rev-parse", "--show-toplevel"]);
+                const planDir = `${root}/.ase/plan/`;
+                const planFile = path.join(planDir, `${argv.id}.md`);
+                if (!fs.existsSync(planDir))
+                    await mkdirp(planDir);
+                const editor = process.env.EDITOR ?? "vi";
+                await execa(editor, [planFile], { stdio: "inherit" });
+            }
+        })
+            .demandCommand(1, "You need to specify a sub-command");
+    },
+    handler: () => { }
+};
+export default planCommand;

package/dst/ase-service.js

@@ -0,0 +1,309 @@
+/*
+**  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 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";
+const SERVE_ENV = "ASE_SERVICE_SERVE";
+const HOST = "127.0.0.1";
+const IDLE_MS = 30 * 60 * 1000;
+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;
+    }
+};
+/*  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");
+    /*  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>"}`);
+    /*  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;
+        }
+    }
+    /*  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");
+    /*  return context information  */
+    return {
+        projectId,
+        port,
+        svcPath: finalSvc,
+        aseDir
+    };
+};
+/*  try binding a single candidate port to verify availability  */
+const tryBind = (port) => {
+    return new Promise((resolve) => {
+        const s = net.createServer();
+        s.once("error", () => {
+            resolve(false);
+        });
+        s.once("listening", () => {
+            s.close(() => resolve(true));
+        });
+        s.listen(port, HOST);
+    });
+};
+/*  allocate a fresh random port in PORT_MIN..PORT_MAX  */
+const allocatePort = async () => {
+    for (let i = 0; i < PORT_TRIES; i++) {
+        const p = PORT_MIN + Math.floor(Math.random() * (PORT_MAX - PORT_MIN + 1));
+        if (await tryBind(p))
+            return p;
+    }
+    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");
+};
+/*  distinguish ECONNREFUSED from other Axios transport errors  */
+const isConnRefused = (err) => {
+    const e = err;
+    return e?.code === "ECONNREFUSED" || e?.cause?.code === "ECONNREFUSED";
+};
+/*  probe the service  */
+const probe = async (port) => {
+    try {
+        const r = await axios.request({
+            method: "OPTIONS",
+            url: `http://${HOST}:${port}/`,
+            timeout: 2000,
+            validateStatus: () => true
+        });
+        return r.status;
+    }
+    catch (err) {
+        if (isConnRefused(err))
+            return null;
+        throw err;
+    }
+};
+/*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
+const runService = async (ctx) => {
+    /*  establish HAPI HTTP/REST service  */
+    const server = Hapi.server({ host: HOST, port: ctx.port });
+    /*  track last activity  */
+    let lastActivity = Date.now();
+    server.ext("onRequest", (_request, h) => {
+        lastActivity = Date.now();
+        return h.continue;
+    });
+    /*  listen to HTTP/REST endpoints  */
+    server.route({
+        method: "OPTIONS",
+        path: "/",
+        handler: (_request, h) => {
+            return h.response().code(204);
+        }
+    });
+    server.route({
+        method: "GET",
+        path: "/stop",
+        handler: (_request, h) => {
+            setImmediate(async () => {
+                await server.stop({ timeout: 1000 });
+                process.exit(0);
+            });
+            return h.response({ ok: true }).code(200);
+        }
+    });
+    server.route({
+        method: "POST",
+        path: "/command",
+        options: { payload: { parse: true, allow: "application/json" } },
+        handler: (request, h) => {
+            const payload = request.payload;
+            if (!payload || typeof payload.command !== "string")
+                return h.response({ error: "missing or invalid 'command' field" }).code(400);
+            if (payload.command === "foo") {
+                return h.response({
+                    ok: true,
+                    projectId: ctx.projectId,
+                    command: "Hello World" // FIXME
+                }).code(200);
+            }
+            else
+                return h.response({ error: "invalid 'command' field" }).code(400);
+        }
+    });
+    /*  start service  */
+    try {
+        await server.start();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "EADDRINUSE") {
+            /*  race-loser re-probe: another "ase service start" won the race  */
+            const status = await probe(ctx.port).catch(() => null);
+            if (status !== null && status >= 200 && status < 300)
+                process.exit(0);
+            process.stderr.write(`ase: service: port ${ctx.port} in use, but not responding!\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`ase: service: ${e.message}\n`);
+        process.exit(1);
+    }
+    /*  stop service after idle timeout  */
+    setInterval(() => {
+        if (Date.now() - lastActivity > IDLE_MS) {
+            server.stop({ timeout: 1000 }).then(() => {
+                process.exit(0);
+            });
+        }
+    }, TICK_MS).unref();
+};
+/*  spawn the current executable detached as a background service  */
+const spawnDetached = (aseDir) => {
+    fs.mkdirSync(aseDir, { recursive: true });
+    const logFile = path.join(aseDir, "service.log");
+    const log = fs.openSync(logFile, "a");
+    const child = spawn(process.execPath, [process.argv[1], "service", "start"], {
+        detached: true,
+        env: { ...process.env, [SERVE_ENV]: "1" },
+        stdio: ["ignore", log, log]
+    });
+    child.unref();
+};
+/*  start flow: ensure port, probe, optionally detach  */
+const doStart = async () => {
+    const ctx = loadContext();
+    let port = ctx.port;
+    if (port === null) {
+        port = await allocatePort();
+        persistPort(ctx.svcPath, port);
+    }
+    if (process.env[SERVE_ENV] === "1") {
+        await runService({ ...ctx, port });
+        return await new Promise(() => { });
+    }
+    const status = await probe(port);
+    if (status !== null && status >= 200 && status < 300)
+        return 0;
+    spawnDetached(ctx.aseDir);
+    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)
+            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)
+        return 0;
+    try {
+        const r = await axios.request({
+            method: "GET",
+            url: `http://${HOST}:${ctx.port}/stop`,
+            timeout: 5000,
+            validateStatus: () => true
+        });
+        return r.status >= 200 && r.status < 300 ? 0 : 1;
+    }
+    catch (err) {
+        if (isConnRefused(err))
+            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 {
+        const r = await axios.request({
+            method: "POST",
+            url: `http://${HOST}:${ctx.port}/command`,
+            headers: { "Content-Type": "application/json" },
+            data: { command: cmd },
+            timeout: 0,
+            validateStatus: () => true,
+            responseType: "text",
+            transformResponse: [(x) => x]
+        });
+        const body = typeof r.data === "string" ? r.data : JSON.stringify(r.data);
+        process.stdout.write(body);
+        if (!body.endsWith("\n"))
+            process.stdout.write("\n");
+        return r.status >= 200 && r.status < 300 ? 0 : 1;
+    }
+    catch (err) {
+        if (isConnRefused(err))
+            throw new Error("service not running (connection refused)");
+        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  */
+    }
+};
+export default serviceCommand;

package/dst/ase-setup.js

@@ -0,0 +1,19 @@
+/*
+**  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>
+*/
+const setupCommand = {
+    command: "setup",
+    describe: "Setup ASE",
+    builder: (yargs) => {
+        return yargs;
+    },
+    handler: (argv) => {
+        if (argv.debug)
+            console.log("DEBUG: setup command");
+        console.log("Setup ASE...");
+        /*  TODO: implement setup logic  */
+    }
+};
+export default setupCommand;

package/dst/ase.js

@@ -6,24 +6,38 @@
 */
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
-import initCommand from "./ase-init.js";
 import configCommand from "./ase-config.js";
-import agentCommand from "./ase-agent.js";
+import setupCommand from "./ase-setup.js";
+import serviceCommand from "./ase-service.js";
 /*  parse CLI arguments  */
-yargs(hideBin(process.argv))
-    .scriptName("ase")
-    .usage("Usage: $0 <command> [options]")
-    .option("debug", {
-    alias: "d",
-    type: "boolean",
-    describe: "Enable debug output",
-    default: false
-})
-    .command(initCommand)
-    .command(configCommand)
-    .command(agentCommand)
-    .demandCommand(1, "You need to specify a command")
-    .help()
-    .version()
-    .strict()
-    .parse();
+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();
+}
+catch (err) {
+    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.4",
+    "version":                              "0.0.6",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -18,27 +18,32 @@
     "devDependencies": {
         "eslint":                           "9.39.4",
         "@eslint/js":                       "9.39.4",
-        "@typescript-eslint/parser":        "8.58.0",
-        "@typescript-eslint/eslint-plugin": "8.58.0",
+        "@typescript-eslint/parser":        "8.58.2",
+        "@typescript-eslint/eslint-plugin": "8.58.2",
         "eslint-plugin-n":                  "17.24.0",
         "eslint-plugin-promise":            "7.2.1",
         "eslint-plugin-import":             "2.32.0",
         "neostandard":                      "0.13.0",
-        "globals":                          "17.4.0",
-        "typescript":                       "6.0.2",
+        "globals":                          "17.5.0",
+        "typescript":                       "6.0.3",
 
-        "@rse/stx":                         "1.1.4",
+        "@rse/stx":                         "1.1.5",
         "nodemon":                          "3.1.14",
         "shx":                              "0.4.0",
         "remark-cli":                       "12.0.1",
         "remark":                           "15.0.1",
         "remark-man":                       "9.0.0",
 
-        "@types/node":                      "25.5.2",
+        "@types/node":                      "25.6.0",
         "@types/yargs":                     "17.0.35"
     },
     "dependencies": {
-        "yargs":                            "18.0.0"
+        "yargs":                            "18.0.0",
+        "yaml":                             "2.8.3",
+        "execa":                            "9.6.1",
+        "mkdirp":                           "3.0.1",
+        "@hapi/hapi":                       "21.4.8",
+        "axios":                            "1.15.0"
     },
     "engines": {
         "npm":                              ">=10.0.0",