@rse/ase 0.0.27 → 0.0.29

package/dst/ase-task.js

@@ -4,96 +4,140 @@
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 import path from "node:path";
-import os from "node:os";
 import fs from "node:fs";
 import { execaSync } from "execa";
 import { DateTime } from "luxon";
-/*  validate the task id to keep it safe as a filename component  */
-const validateId = (id) => {
-    if (typeof id !== "string" || id.length === 0)
-        throw new Error("task: id must be a non-empty string");
-    if (!/^[A-Za-z0-9-]+$/.test(id))
-        throw new Error("task: id must match [A-Za-z0-9-]+");
-};
-/*  resolve the on-disk path for a given task id  */
-const taskPath = (id) => {
-    validateId(id);
-    return path.join(os.homedir(), ".ase", "task", id, "plan.md");
-};
-/*  load a task; returns empty string if no task exists  */
-export const taskLoad = (id) => {
-    const file = taskPath(id);
-    if (!fs.existsSync(file))
-        return "";
-    return fs.readFileSync(file, "utf8");
-};
-/*  save a task as UTF-8 text under the given id; the task's home
-    directory ~/.ase/task/<id>/ is owned by ASE and removed in full
-    by taskDelete, so callers must not place foreign files there  */
-export const taskSave = (id, text) => {
-    if (typeof text !== "string")
-        throw new Error("task: text must be a string");
-    const file = taskPath(id);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, text, "utf8");
-};
-/*  delete a task by id; removes the entire task home directory
-    ~/.ase/task/<id>/ (owned by ASE); returns true if a task existed  */
-export const taskDelete = (id) => {
-    const file = taskPath(id);
-    if (!fs.existsSync(file))
-        return false;
-    fs.rmSync(path.dirname(file), { recursive: true, force: true });
-    return true;
-};
-/*  list all persisted tasks in lexicographic id order; if verbose is true,
-    each entry's `mtime` is set to the `plan.md` modification time formatted
-    as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
-export const taskList = (verbose = false) => {
-    const dir = path.join(os.homedir(), ".ase", "task");
-    if (!fs.existsSync(dir))
-        return [];
-    const out = [];
-    for (const entry of fs.readdirSync(dir)) {
-        if (!/^[A-Za-z0-9-]+$/.test(entry))
-            continue;
-        const file = path.join(dir, entry, "plan.md");
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema, parseScope } from "./ase-config.js";
+/*  reusable functionality: persisted task plans under
+    <project>/.ase/task/<id>/plan.md  */
+export class Task {
+    /*  validate the task id to keep it safe as a filename component  */
+    static validateId(id) {
+        if (typeof id !== "string" || id.length === 0)
+            throw new Error("task: id must be a non-empty string");
+        if (!/^[A-Za-z0-9-]+$/.test(id))
+            throw new Error("task: id must match [A-Za-z0-9-]+");
+    }
+    /*  determine the project root (Git top-level if inside a Git
+        working tree, otherwise the current working directory)  */
+    static projectRoot() {
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" });
+            const top = result.stdout.trim();
+            if (top !== "")
+                return top;
+        }
+        catch {
+            /*  not inside a Git working tree  */
+        }
+        return process.cwd();
+    }
+    /*  resolve the on-disk base directory for task storage  */
+    static baseDir() {
+        return path.join(Task.projectRoot(), ".ase", "task");
+    }
+    /*  resolve the on-disk path for a given task id  */
+    static path(id) {
+        Task.validateId(id);
+        return path.join(Task.baseDir(), id, "plan.md");
+    }
+    /*  load a task; returns empty string if no task exists  */
+    static load(id) {
+        const file = Task.path(id);
         if (!fs.existsSync(file))
-            continue;
-        const st = fs.statSync(file);
-        if (!st.isFile())
-            continue;
-        const mtime = verbose ? DateTime.fromJSDate(st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined;
-        out.push({ id: entry, mtime });
+            return "";
+        return fs.readFileSync(file, "utf8");
     }
-    out.sort((a, b) => a.id.localeCompare(b.id));
-    return out;
-};
-/*  purge tasks whose modification time is older than the given cutoff in
-    milliseconds; returns the list of removed task ids  */
-export const taskPurge = (maxAgeMs) => {
-    const dir = path.join(os.homedir(), ".ase", "task");
-    if (!fs.existsSync(dir))
-        return [];
-    const cutoff = Date.now() - maxAgeMs;
-    const removed = [];
-    for (const entry of fs.readdirSync(dir)) {
-        if (!/^[A-Za-z0-9-]+$/.test(entry))
-            continue;
-        const sub = path.join(dir, entry);
-        const file = path.join(sub, "plan.md");
+    /*  save a task as UTF-8 text under the given id; the task's home
+        directory <project>/.ase/task/<id>/ is owned by ASE and removed
+        in full by Task.delete, so callers must not place foreign files there  */
+    static save(id, text) {
+        if (typeof text !== "string")
+            throw new Error("task: text must be a string");
+        const file = Task.path(id);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, text, "utf8");
+    }
+    /*  delete a task by id; removes the entire task home directory
+        <project>/.ase/task/<id>/ (owned by ASE); returns true if a task existed  */
+    static delete(id) {
+        const file = Task.path(id);
         if (!fs.existsSync(file))
-            continue;
-        const st = fs.statSync(file);
-        if (!st.isFile())
-            continue;
-        if (st.mtimeMs < cutoff) {
-            fs.rmSync(sub, { recursive: true, force: true });
-            removed.push(entry);
+            return false;
+        fs.rmSync(path.dirname(file), { recursive: true, force: true });
+        return true;
+    }
+    /*  list all persisted tasks in lexicographic id order; if verbose is true,
+        each entry's `mtime` is set to the `plan.md` modification time formatted
+        as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
+    static list(verbose = false) {
+        const dir = Task.baseDir();
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const entry of fs.readdirSync(dir)) {
+            if (!/^[A-Za-z0-9-]+$/.test(entry))
+                continue;
+            const file = path.join(dir, entry, "plan.md");
+            if (!fs.existsSync(file))
+                continue;
+            const st = fs.statSync(file);
+            if (!st.isFile())
+                continue;
+            const mtime = verbose ? DateTime.fromJSDate(st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined;
+            out.push({ id: entry, mtime });
         }
+        out.sort((a, b) => a.id.localeCompare(b.id));
+        return out;
     }
-    return removed;
-};
+    /*  purge tasks whose modification time is older than the given cutoff in
+        milliseconds; returns the list of removed task ids  */
+    static purge(maxAgeMs) {
+        const dir = Task.baseDir();
+        if (!fs.existsSync(dir))
+            return [];
+        const cutoff = Date.now() - maxAgeMs;
+        const removed = [];
+        for (const entry of fs.readdirSync(dir)) {
+            if (!/^[A-Za-z0-9-]+$/.test(entry))
+                continue;
+            const sub = path.join(dir, entry);
+            const file = path.join(sub, "plan.md");
+            if (!fs.existsSync(file))
+                continue;
+            const st = fs.statSync(file);
+            if (!st.isFile())
+                continue;
+            if (st.mtimeMs < cutoff) {
+                fs.rmSync(sub, { recursive: true, force: true });
+                removed.push(entry);
+            }
+        }
+        return removed;
+    }
+    /*  get the active task id for a given session, or empty string if none  */
+    static getId(log, session) {
+        const scope = parseScope(`session:${session}`);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.read();
+        const val = cfg.get("agent.task");
+        if (val === undefined)
+            return "";
+        return String(isScalar(val) ? val.value : val);
+    }
+    /*  set the active task id for a given session  */
+    static setId(log, session, id) {
+        const scope = parseScope(`session:${session}`);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.lock(() => {
+            cfg.read();
+            cfg.set("agent.task", id);
+            cfg.write();
+        });
+    }
+}
 /*  read all of stdin as a UTF-8 string  */
 const readStdin = () => {
     return new Promise((resolve, reject) => {
@@ -114,7 +158,7 @@ export default class TaskCommand {
         /*  register CLI top-level command "ase task"  */
         const task = program
             .command("task")
-            .description("Manage persisted tasks under ~/.ase/task/<id>/plan.md")
+            .description("Manage persisted tasks under <project>/.ase/task/<id>/plan.md")
             .action(() => {
             task.outputHelp();
             process.exit(1);
@@ -125,7 +169,7 @@ export default class TaskCommand {
             .description("List all persisted task ids, one per line")
             .option("-v, --verbose", "also show the plan.md modification time as (YYYY-MM-DD HH:MM)")
             .action((opts) => {
-            const items = taskList(opts.verbose ?? false);
+            const items = Task.list(opts.verbose ?? false);
             for (const item of items) {
                 if (opts.verbose)
                     process.stdout.write(`${item.id}\t(${item.mtime})\n`);
@@ -140,7 +184,7 @@ export default class TaskCommand {
             .description("Load a task by id and write it to stdout")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const text = taskLoad(id);
+            const text = Task.load(id);
             process.stdout.write(text);
             process.exit(0);
         });
@@ -150,7 +194,7 @@ export default class TaskCommand {
             .description("Edit a task by id with $EDITOR")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const file = taskPath(id);
+            const file = Task.path(id);
             const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
             fs.mkdirSync(path.dirname(file), { recursive: true });
             if (!fs.existsSync(file))
@@ -166,7 +210,7 @@ export default class TaskCommand {
             .argument("<id>", "Task identifier")
             .action(async (id) => {
             const text = await readStdin();
-            taskSave(id, text);
+            Task.save(id, text);
             this.log.write("info", `task: saved "${id}"`);
             process.exit(0);
         });
@@ -176,7 +220,7 @@ export default class TaskCommand {
             .description("Delete a task by id")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const removed = taskDelete(id);
+            const removed = Task.delete(id);
             if (removed)
                 this.log.write("info", `task: removed "${id}"`);
             else
@@ -186,13 +230,24 @@ export default class TaskCommand {
         /*  register CLI sub-command "ase task purge"  */
         task
             .command("purge")
-            .description("Remove all tasks with a modification time older than <days> (default: 31)")
-            .argument("[<days>]", "Maximum task age in days", "31")
-            .action((days) => {
-            const n = Number.parseInt(days, 10);
-            if (!Number.isFinite(n) || n < 0)
-                throw new Error("task: <days> must be a non-negative integer");
-            const removed = taskPurge(n * 24 * 60 * 60 * 1000);
+            .description("Remove all tasks with a modification time older than <age> (default: 31d); " +
+            "<age> is <number><unit> with unit h (hour), d (day), m (month), y (year)")
+            .argument("[<age>]", "Maximum task age as <number><unit>", "31d")
+            .action((age) => {
+            const m = /^(\d+)([hdmy])$/.exec(age);
+            if (m === null)
+                throw new Error("task: <age> must match <number><unit> with unit h, d, m, or y");
+            const n = Number.parseInt(m[1], 10);
+            const unit = m[2];
+            const hour = 60 * 60 * 1000;
+            const day = 24 * hour;
+            const month = 30 * day;
+            const year = 365 * day;
+            const factor = unit === "h" ? hour :
+                unit === "d" ? day :
+                    unit === "m" ? month :
+                        year;
+            const removed = Task.purge(n * factor);
             if (removed.length === 0)
                 this.log.write("info", "task: no tasks to purge");
             else
@@ -202,3 +257,160 @@ export default class TaskCommand {
         });
     }
 }
+/*  MCP registration entry point for task tools  */
+export class TaskMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    register(mcp) {
+        mcp.registerTool("task_list", {
+            title: "ASE task list",
+            description: "List all persisted tasks. " +
+                "Returns a `tasks` array (in lexicographic `id` order) where each item has the " +
+                "task `id`. If `verbose` is `true`, each item additionally has an `mtime` field " +
+                "(last modification time of the task's `plan.md`, formatted as `YYYY-MM-DD HH:MM`). " +
+                "Returns an empty array if no tasks exist.",
+            inputSchema: {
+                verbose: z.boolean().optional()
+                    .describe("if true, also include the `mtime` field per task (default: false)")
+            },
+            outputSchema: {
+                tasks: z.array(z.object({
+                    id: z.string().describe("task identifier"),
+                    mtime: z.string().optional()
+                        .describe("plan.md modification time (`YYYY-MM-DD HH:MM`); only present if `verbose` is true")
+                })).describe("all persisted tasks in lexicographic id order")
+            }
+        }, async (args) => {
+            try {
+                const verbose = args.verbose ?? false;
+                const items = Task.list(verbose);
+                const tasks = verbose ?
+                    items.map((item) => ({ id: item.id, mtime: item.mtime })) :
+                    items.map((item) => ({ id: item.id }));
+                const result = { tasks };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `task_list: ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("task_load", {
+            title: "ASE task load",
+            description: "Load a previously persisted task by `id`. " +
+                "Returns the task as `text`; returns an empty string if no task exists for the `id`.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+            }
+        }, async (args) => {
+            try {
+                const text = Task.load(args.id);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `task_load: ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("task_save", {
+            title: "ASE task save",
+            description: "Persist a task as `text` under `id`. " +
+                "Overwrites any existing task for the same `id`.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')"),
+                text: z.string()
+                    .describe("text content of the task")
+            }
+        }, async (args) => {
+            try {
+                Task.save(args.id, args.text);
+                return {
+                    content: [{ type: "text", text: `task_save: OK: saved task "${args.id}"` }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `task_save: ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("task_delete", {
+            title: "ASE task delete",
+            description: "Delete a previously persisted task by `id`. " +
+                "Returns a status `text` indicating whether a task existed and was removed.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+            }
+        }, async (args) => {
+            try {
+                const removed = Task.delete(args.id);
+                const msg = removed ?
+                    `task_delete: OK: removed task "${args.id}"` :
+                    `task_delete: WARNING: no task "${args.id}" to remove`;
+                return {
+                    content: [{ type: "text", text: msg }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `task_delete: ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("task_id", {
+            title: "ASE task id get/set",
+            description: "Get or set the active ASE task `id` for a given `session`. " +
+                "If `id` is provided, it sets the task id in the given `session`, " +
+                "otherwise it returns the current task `id` of the `session`.",
+            inputSchema: {
+                id: z.string().optional()
+                    .describe("task identifier to set (allowed characters: A-Z, a-z, 0-9, '-'); " +
+                    "if omitted, the current task id is returned"),
+                session: z.string()
+                    .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+            }
+        }, async (args) => {
+            try {
+                if (args.id !== undefined) {
+                    Task.setId(this.log, args.session, args.id);
+                    const msg = `task_id: OK: set agent.task to "${args.id}" ` +
+                        `for session "${args.session}"`;
+                    return {
+                        content: [{ type: "text", text: msg }]
+                    };
+                }
+                const text = Task.getId(this.log, args.session);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `task_id: ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-timestamp.js

@@ -0,0 +1,36 @@
+/*
+**  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 { z } from "zod";
+import { DateTime } from "luxon";
+/*  MCP registration entry point for timestamp tool  */
+export class TimestampMCP {
+    register(mcp) {
+        mcp.registerTool("timestamp", {
+            title: "ASE timestamp",
+            description: "Return the current local date/time formatted via a Luxon format string. " +
+                "Pass the Luxon format tokens as `format` (default: `yyyy-LL-dd HH:mm`). " +
+                "Returns the formatted timestamp as `text`.",
+            inputSchema: {
+                format: z.string().default("yyyy-LL-dd HH:mm")
+                    .describe("Luxon format tokens (default: `yyyy-LL-dd HH:mm`)")
+            }
+        }, async (args) => {
+            try {
+                const text = DateTime.now().toFormat(args.format);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `timestamp: format failed: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase.js

@@ -42,14 +42,14 @@ const main = async () => {
         log.logFile(opts.logFile);
     });
     /*  register top-level commands  */
+    new SetupCommand(log).register(program);
     new ConfigCommand(log).register(program);
-    new ServiceCommand(log).register(program);
     new MCPCommand(log).register(program);
+    new ServiceCommand(log).register(program);
     new HookCommand(log).register(program);
-    new DiagramCommand(log).register(program);
-    new SetupCommand(log).register(program);
     new StatuslineCommand(log).register(program);
     new TaskCommand(log).register(program);
+    new DiagramCommand(log).register(program);
     /*  parse program arguments  */
     await program.parseAsync(process.argv);
     /*  gracefully terminate  */

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.27",
+    "version":                              "0.0.29",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -33,7 +33,10 @@
         "@types/node":                      "25.8.0",
         "@types/luxon":                     "3.7.1",
         "@types/which":                     "3.0.4",
-        "@types/update-notifier":           "6.0.8"
+        "@types/update-notifier":           "6.0.8",
+        "@types/shell-quote":               "1.7.5",
+        "@types/proper-lockfile":           "4.1.4",
+        "@types/write-file-atomic":         "4.0.3"
     },
     "dependencies": {
         "commander":                        "14.0.3",
@@ -51,7 +54,10 @@
         "@modelcontextprotocol/sdk":        "1.29.0",
         "zod":                              "4.4.3",
         "which":                            "7.0.0",
-        "update-notifier":                  "7.3.1"
+        "update-notifier":                  "7.3.1",
+        "shell-quote":                      "1.8.3",
+        "proper-lockfile":                  "4.1.2",
+        "write-file-atomic":                "4.0.0"
     },
     "engines": {
         "npm":                              ">=10.0.0",