@rse/ase 0.0.16 → 0.0.17

package/dst/ase-config.js

@@ -151,7 +151,7 @@ const hasProjectContext = () => {
     "project" term is implicitly added only when a project context
     exists (Git repository or ".ase" directory at or above cwd), and
     an explicit "project" term requires that same context  */
-const parseScope = (value) => {
+export const parseScope = (value) => {
     const projectActive = hasProjectContext();
     const input = (value === undefined || value === "") ?
         (projectActive ? "project" : "user") :

package/dst/ase-hook.js

@@ -6,14 +6,40 @@
 import path from "node:path";
 import fs from "node:fs";
 import { execaSync } from "execa";
+import Version from "./ase-version.js";
+import { Config, configSchema, parseScope } from "./ase-config.js";
 /*  CLI command "ase hook"  */
 export default class HookCommand {
     log;
     constructor(log) {
         this.log = log;
     }
+    /*  recursively expand "@<path>" file references in a Markdown text,
+        resolving paths relative to the directory of the containing file  */
+    expandReferences(text, baseDir, visited = new Set()) {
+        return text.replace(/@([^\s]+)/g, (match, ref) => {
+            let resolved = ref;
+            if (resolved.startsWith("~/"))
+                resolved = path.join(process.env.HOME ?? "", resolved.slice(2));
+            const abs = path.isAbsolute(resolved) ? resolved : path.resolve(baseDir, resolved);
+            if (visited.has(abs))
+                return match;
+            if (!fs.existsSync(abs))
+                return match;
+            let content;
+            try {
+                content = fs.readFileSync(abs, "utf8");
+            }
+            catch (_e) {
+                return match;
+            }
+            const next = new Set(visited);
+            next.add(abs);
+            return this.expandReferences(content, path.dirname(abs), next);
+        });
+    }
     /*  handler for "ase hook session-start"  */
-    doSessionStart() {
+    async doSessionStart() {
         /*  determine plugin root  */
         const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? "";
         if (pluginRoot === "")
@@ -25,34 +51,85 @@ export default class HookCommand {
         const pkg = fs.readFileSync(filePkg, "utf8");
         let md = fs.readFileSync(fileMd, "utf8");
         /*  determine own version  */
-        const version = JSON.parse(pkg).version ?? "";
+        const versionCurrentPlugin = JSON.parse(pkg).version ?? "";
+        const versionCurrentTool = Version.current();
+        const versionLatestTool = await Version.latest();
+        /*  sanity check situation  */
+        const versionHints = [];
+        if (versionCurrentPlugin !== versionCurrentTool)
+            versionHints.push("**WARNING:** version *mismatch*: " +
+                `tool: **${versionCurrentPlugin}**, plugin: **${versionCurrentTool}**`);
+        if (versionCurrentTool !== versionLatestTool)
+            versionHints.push(`**NOTICE:** *latest* version: **${versionLatestTool}**, please update!`);
+        if (process.env.ASE_SETUP_DEV !== undefined)
+            versionHints.push("**NOTICE:** *development* setup");
+        const versionHint = versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
         /*  read session information  */
         const stdin = fs.readFileSync(0, "utf8");
         const input = stdin.trim() !== "" ? JSON.parse(stdin) : {};
         /*  determine session id  */
         const sessionId = input.session_id ?? "";
+        /*  establish config context  */
+        const cfg = new Config("config", configSchema, this.log, parseScope(`session:${sessionId}`));
+        try {
+            cfg.read();
+        }
+        catch (_e) {
+            /*  best-effort: ignore failures  */
+        }
         /*  determine task id  */
         const taskId = process.env.ASE_TASK_ID ?? "default";
         try {
-            execaSync("ase", ["config", `--scope=session:${sessionId}`, "set", "task.id", taskId], { stdio: ["ignore", "ignore", "ignore"] });
+            cfg.set("task.id", taskId);
+            cfg.write();
         }
         catch (_e) {
             /*  best-effort: ignore failures  */
         }
-        /*  provide session and task id to Claude Code shell commands  */
+        /*  determine project id  */
+        const cwd = input.cwd ?? process.cwd();
+        let projectDir = cwd;
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
+                stderr: "ignore", cwd
+            });
+            if (result.stdout.trim() !== "")
+                projectDir = result.stdout.trim();
+        }
+        catch {
+            /*  not inside a Git working tree  */
+        }
+        const projectId = path.basename(projectDir);
+        /*  determine user id  */
+        const userId = process.env.USER ?? process.env.LOGNAME ?? "unknown";
+        /*  determine agent persona style  */
+        let persona = "engineer";
+        const val = cfg.get("agent.persona.style");
+        if (typeof val === "string")
+            persona = val;
+        /*  provide ASE information to Claude Code shell commands  */
         const envFile = process.env.CLAUDE_ENV_FILE ?? "";
         if (envFile !== "") {
-            const script = `export ASE_VERSION="${version}"\n` +
-                `export ASE_SESSION_ID="${sessionId}"\n` +
-                `export ASE_TASK_ID="${taskId}"\n`;
+            const script = `export ASE_VERSION="${versionCurrentPlugin}"\n` +
+                `export ASE_USER_ID="${userId}"\n` +
+                `export ASE_PROJECT_ID="${projectId}"\n` +
+                `export ASE_TASK_ID="${taskId}"\n` +
+                `export ASE_SESSION_ID="${sessionId}"\n`;
             fs.appendFileSync(envFile, script, "utf8");
         }
         /*  prepend ASE information to constitution markdown  */
         md =
-            `<ase-version>${version}</ase-version>\n` +
+            `<ase-version>${versionCurrentPlugin}</ase-version>\n` +
+                `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
+                `<ase-persona-style>${persona}</ase-persona-style>\n` +
+                `<ase-user-id>${userId}</ase-user-id>\n` +
+                `<ase-project-id>${projectId}</ase-project-id>\n` +
                 `<ase-task-id>${taskId}</ase-task-id>\n` +
                 `<ase-session-id>${sessionId}</ase-session-id>\n` +
                 "\n" + md;
+        /*  expand all @<file> references manually  */
+        md = this.expandReferences(md, path.dirname(fileMd));
+        fs.writeFileSync("/tmp/xxx", md, "utf8");
         /*  inject markdown into session context  */
         process.stdout.write(JSON.stringify({
             "hookSpecificOutput": {
@@ -110,8 +187,8 @@ export default class HookCommand {
         hookCmd
             .command("session-start")
             .description("handle Claude Code SessionStart hook event")
-            .action(() => {
-            process.exit(this.doSessionStart());
+            .action(async () => {
+            process.exit(await this.doSessionStart());
         });
         /*  register CLI sub-command "ase hook pre-tool-use"  */
         hookCmd

package/dst/ase-setup.js

@@ -6,28 +6,42 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
-import pkg from "../package.json" with { type: "json" };
+import which from "which";
+import Version from "./ase-version.js";
 /*  CLI command "ase setup"  */
 export default class SetupCommand {
     log;
     constructor(log) {
         this.log = log;
     }
-    /*  run a sub-process with inherited stdio so users see live output  */
-    async run(cmd, args, cwd) {
-        this.log.write("info", `setup: running: $ ${cmd} ${args.join(" ")}` +
-            (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
-        await execa(cmd, args, { stdio: "inherit", cwd });
+    /*  ensure a tool is available  */
+    async ensureTool(tool) {
+        return which(tool).catch(() => {
+            throw new Error(`mandatory tool "${tool}" not found in $PATH`);
+        });
     }
-    /*  capture stdout of a sub-process  */
-    async capture(cmd, args, cwd) {
-        this.log.write("info", `setup: running: $ ${cmd} ${args.join(" ")}` +
+    /*  run a sub-process, suppressing output on success and emitting it on failure  */
+    async run(cmd, args, cwd) {
+        this.log.write("info", `setup: $ ${cmd} ${args.join(" ")}` +
             (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
-        const r = await execa(cmd, args, { stdio: ["ignore", "pipe", "pipe"], cwd });
-        return r.stdout.trim();
+        await execa(cmd, args, { stdio: "pipe", cwd }).catch((err) => {
+            const exitCode = typeof err?.exitCode === "number" ? err.exitCode : -1;
+            this.log.write("error", `setup: command failed: exit code: ${exitCode}`);
+            if (typeof err?.stdout === "string" && err.stdout.length > 0) {
+                this.log.write("error", "setup: command failed: stdout:");
+                process.stdout.write(err.stdout);
+            }
+            if (typeof err?.stderr === "string" && err.stderr.length > 0) {
+                this.log.write("error", "setup: command failed: stderr:");
+                process.stderr.write(err.stderr);
+            }
+            throw err;
+        });
     }
     /*  handler for "ase setup install"  */
     async doInstall(dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
         this.log.write("info", `setup: install${dev ? "[dev]" : ""}: ` +
             `installing ASE Claude Code plugin (origin: ${dev ? "local" : "remote"})`);
         const source = dev ? process.cwd() : "rse/ase";
@@ -37,6 +51,8 @@ export default class SetupCommand {
     }
     /*  handler for "ase setup update"  */
     async doUpdate(force, dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
         if (dev) {
             /*  update ASE CLI Tool  */
             this.log.write("info", "setup: update[dev]: re-build ASE CLI tool (origin: local)");
@@ -52,15 +68,8 @@ export default class SetupCommand {
         }
         else {
             /*  perform NPM version check  */
-            const current = pkg.version;
-            let latest = "";
-            try {
-                latest = await this.capture("npm", ["view", "@rse/ase", "version"]);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                this.log.write("warning", `setup: update: failed to query latest ASE version: ${message}`);
-            }
+            const current = Version.current();
+            const latest = await Version.latest();
             if (!force && latest !== "" && latest === current) {
                 this.log.write("info", `setup: update: ASE already at latest version ${current}`);
                 return 0;
@@ -77,6 +86,8 @@ export default class SetupCommand {
     }
     /*  handler for "ase setup uninstall"  */
     async doUninstall(dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
         /*  uninstall ASE Claude Code plugin  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             `uninstalling ASE Claude Code plugin (origin: ${dev ? "local" : "remote"})`);

package/dst/ase-version.js

@@ -0,0 +1,27 @@
+/*
+**  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 { execa } from "execa";
+import pkg from "../package.json" with { type: "json" };
+/*  determination of current and available ASE versions  */
+export default class Version {
+    /*  return current ASE version  */
+    static current() {
+        return pkg.version;
+    }
+    /*  return latest ASE version available on the NPM registry  */
+    static async latest() {
+        let latest = "";
+        try {
+            const r = await execa("npm", ["view", "@rse/ase", "version"], { stdio: ["ignore", "pipe", "pipe"] });
+            latest = r.stdout.trim();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`failed to query latest ASE version: ${message}`, { cause: err });
+        }
+        return latest;
+    }
+}

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.16",
+    "version":                              "0.0.17",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -32,7 +32,8 @@
         "shx":                              "0.4.0",
 
         "@types/node":                      "25.6.0",
-        "@types/luxon":                     "3.7.1"
+        "@types/luxon":                     "3.7.1",
+        "@types/which":                     "3.0.4"
     },
     "dependencies": {
         "commander":                        "14.0.3",
@@ -48,7 +49,8 @@
         "pretty-ms":                        "9.3.0",
         "luxon":                            "3.7.2",
         "@modelcontextprotocol/sdk":        "1.29.0",
-        "zod":                              "4.4.2"
+        "zod":                              "4.4.2",
+        "which":                            "6.0.1"
     },
     "engines": {
         "npm":                              ">=10.0.0",