@rse/ase 0.9.4 → 0.9.6

package/dst/ase-artifact.js

@@ -0,0 +1,331 @@
+/*
+**  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 picomatch from "picomatch";
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema } from "./ase-config.js";
+import { Task } from "./ase-task.js";
+/*  the recognized artifact kinds, in descending precedence order;
+    "othr" is the implicit catch-all and is always resolved last  */
+export const artifactKinds = ["spec", "arch", "code", "docs", "infr", "othr"];
+/*  the five configured kinds (i.e. all kinds except the implicit "othr")  */
+const configuredKinds = ["spec", "arch", "code", "docs", "infr"];
+/*  reusable functionality: resolve artifact kinds to project-relative
+    file lists, driven by the "project.artifact.<kind>" configuration  */
+export class Artifact {
+    /*  validate a requested kind against the known set  */
+    static validateKind(kind) {
+        if (!artifactKinds.includes(kind))
+            throw new Error(`artifact: unknown kind "${kind}" ` +
+                `(expected one of: ${artifactKinds.join(", ")})`);
+        return kind;
+    }
+    /*  translate a single ".gitignore" line into a picomatch-backed rule,
+        honoring the anchored-vs-floating, directory-only, and negation
+        semantics of ".gitignore" patterns  */
+    static compileIgnoreRule(line) {
+        let pattern = line.trim();
+        if (pattern === "" || pattern.startsWith("#"))
+            return null;
+        let negated = false;
+        if (pattern.startsWith("!")) {
+            negated = true;
+            pattern = pattern.slice(1);
+        }
+        let dirOnly = false;
+        if (pattern.endsWith("/")) {
+            dirOnly = true;
+            pattern = pattern.slice(0, -1);
+        }
+        const anchored = pattern.includes("/");
+        if (pattern.startsWith("/"))
+            pattern = pattern.slice(1);
+        const glob = anchored ? pattern : `**/${pattern}`;
+        const isMatch = picomatch(glob, { dot: true });
+        return { matcher: (p) => isMatch(p), negated, dirOnly };
+    }
+    /*  load the ".gitignore" rules located directly in a directory  */
+    static loadIgnoreRules(dir) {
+        const file = path.join(dir, ".gitignore");
+        if (!fs.existsSync(file))
+            return [];
+        const rules = [];
+        for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+            const rule = Artifact.compileIgnoreRule(line);
+            if (rule !== null)
+                rules.push(rule);
+        }
+        return rules;
+    }
+    /*  decide whether a project-relative path is ignored by the given
+        ordered ".gitignore" rule set (last matching rule wins)  */
+    static isIgnored(rel, isDir, rules) {
+        let ignored = false;
+        for (const rule of rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.matcher(rel))
+                ignored = !rule.negated;
+        }
+        return ignored;
+    }
+    /*  build the file universe by walking the project tree from the
+        project root, honoring ".gitignore" rules (root plus nested) and
+        always pruning ".git". Yields POSIX project-relative, sorted,
+        de-duplicated file paths  */
+    static universe() {
+        const root = Task.projectRoot();
+        const files = new Set();
+        const walk = (dir, relDir, inherited) => {
+            const rules = [...inherited, ...Artifact.loadIgnoreRules(dir)];
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.name === ".git")
+                    continue;
+                const rel = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+                const isDir = entry.isDirectory();
+                if (Artifact.isIgnored(rel, isDir, rules))
+                    continue;
+                if (isDir)
+                    walk(path.join(dir, entry.name), rel, rules);
+                else if (entry.isFile())
+                    files.add(rel);
+            }
+        };
+        walk(root, "", []);
+        return [...files].sort((a, b) => a.localeCompare(b));
+    }
+    /*  raw-resolve a single kind's configuration spec against the file
+        universe via "seed-then-mutate" miniglob semantics: the spec is a
+        whitespace-separated list of tokens.  */
+    static rawResolve(spec, all) {
+        const tokens = spec.split(/\s+/).filter((t) => t !== "");
+        if (tokens.length === 0)
+            return new Set();
+        const result = new Set(tokens[0].startsWith("!") ? all : []);
+        for (const token of tokens) {
+            const negated = token.startsWith("!");
+            const glob = negated ? token.slice(1) : token;
+            if (glob === "")
+                continue;
+            const isMatch = picomatch(glob, { dot: true });
+            for (const file of all) {
+                if (!isMatch(file))
+                    continue;
+                if (negated)
+                    result.delete(file);
+                else
+                    result.add(file);
+            }
+        }
+        return result;
+    }
+    /*  read a single scalar configuration value as a plain string  */
+    static configString(cfg, key) {
+        const val = cfg.get(key);
+        if (val === undefined)
+            return "";
+        return String(isScalar(val) ? val.value : val);
+    }
+    /*  read the configured "basedir" anchor and "files" miniglob spec
+        for a single kind; "basedir" is project-root-relative (POSIX,
+        "" ≡ project root) and "files" resolves relative to "basedir"  */
+    static spec(log, kind) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const basedir = Artifact.configString(cfg, `project.artifact.${kind}.basedir`)
+            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
+            .replace(/^\.$/, "");
+        const files = Artifact.configString(cfg, `project.artifact.${kind}.files`);
+        return { basedir, files };
+    }
+    /*  raw-resolve a single kind's "basedir"/"files" spec against the
+        file universe: the "files" miniglob resolves relative to
+        "basedir", then matches are re-prefixed with "basedir" to stay
+        project-relative  */
+    static resolveKind(basedir, files, all) {
+        if (basedir === "")
+            return Artifact.rawResolve(files, all);
+        const prefix = `${basedir}/`;
+        const local = all
+            .filter((file) => file.startsWith(prefix))
+            .map((file) => file.slice(prefix.length));
+        const result = new Set();
+        for (const file of Artifact.rawResolve(files, local))
+            result.add(`${prefix}${file}`);
+        return result;
+    }
+    /*  resolve the requested kinds to project-relative file lists  */
+    static list(log, kinds) {
+        const all = Artifact.universe();
+        /*  raw-resolve all five configured kinds  */
+        const raw = new Map();
+        for (const kind of configuredKinds) {
+            const { basedir, files } = Artifact.spec(log, kind);
+            raw.set(kind, Artifact.resolveKind(basedir, files, all));
+        }
+        /*  partition the universe by descending precedence  */
+        const claimed = new Set();
+        const part = new Map();
+        for (const kind of configuredKinds) {
+            const own = [];
+            for (const file of raw.get(kind).size > 0 ? all : []) {
+                if (raw.get(kind).has(file) && !claimed.has(file)) {
+                    own.push(file);
+                    claimed.add(file);
+                }
+            }
+            part.set(kind, own);
+        }
+        part.set("othr", all.filter((file) => !claimed.has(file)));
+        /*  project onto the requested kinds  */
+        return kinds.map((kind) => ({
+            kind,
+            files: part.get(kind) ?? []
+        }));
+    }
+    /*  resolve a base-relative "filename" within a kind's "basedir" to a
+        project-root-relative POSIX path; the implicit "othr" catch-all
+        has no configured "basedir" and is therefore rejected  */
+    static name(log, kind, filename) {
+        if (kind === "othr")
+            throw new Error("artifact: kind \"othr\" has no configured basedir");
+        const file = filename.replace(/\\/g, "/").replace(/^\/+/, "");
+        if (file === "")
+            throw new Error("artifact: filename must not be empty");
+        const { basedir } = Artifact.spec(log, kind);
+        return basedir === "" ? file : `${basedir}/${file}`;
+    }
+}
+/*  CLI command "ase artifact"  */
+export default class ArtifactCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase artifact"  */
+        const artifact = program
+            .command("artifact")
+            .description("Resolve project artifact kinds to project-relative file lists")
+            .action(() => {
+            artifact.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase artifact list"  */
+        artifact
+            .command("list")
+            .description("Resolve one or more artifact kinds to project-relative file paths")
+            .option("--kind <kinds>", "comma-separated list of artifact kinds " +
+            `(${artifactKinds.join("|")})`, artifactKinds.join(","))
+            .action((opts) => {
+            const kinds = opts.kind.split(",").map((k) => Artifact.validateKind(k.trim()));
+            const result = Artifact.list(this.log, kinds);
+            const single = result.length === 1;
+            for (const { kind, files } of result) {
+                if (!single)
+                    process.stdout.write(`# ${kind}:\n`);
+                for (const file of files)
+                    process.stdout.write(`- ${file}\n`);
+            }
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase artifact name"  */
+        artifact
+            .command("name")
+            .description("Resolve a base-relative filename within an artifact kind to a project-relative path")
+            .argument("<filename>", "base-relative filename within the kind's basedir")
+            .option("--kind <kind>", "artifact kind " +
+            `(${configuredKinds.join("|")})`, "code")
+            .action((filename, opts) => {
+            const kind = Artifact.validateKind(opts.kind.trim());
+            process.stdout.write(`${Artifact.name(this.log, kind, filename)}\n`);
+            process.exit(0);
+        });
+    }
+}
+/*  MCP registration entry point for artifact tools  */
+export class ArtifactMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register MCP tools  */
+    register(mcp) {
+        mcp.registerTool("ase_artifact_list", {
+            title: "ASE artifact list",
+            description: "Resolve one or more artifact `kind`s to project-relative file lists. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, `infr`, and `othr`. " +
+                "Returns an `artifacts` array of `{ kind, files }` objects. " +
+                "If `kind` is omitted or empty, all kinds are resolved.",
+            inputSchema: {
+                kind: z.array(z.string()).optional()
+                    .describe("list of artifact kinds (`spec`, `arch`, `code`, `docs`, `infr`, " +
+                    "`othr`); if omitted or empty, all kinds are resolved")
+            },
+            outputSchema: {
+                artifacts: z.array(z.object({
+                    kind: z.string().describe("artifact kind"),
+                    files: z.array(z.string()).describe("project-relative file paths for the kind")
+                })).describe("resolved artifacts, one entry per requested kind")
+            }
+        }, async (args) => {
+            try {
+                const requested = args.kind !== undefined && args.kind.length > 0 ?
+                    args.kind : [...artifactKinds];
+                const kinds = requested.map((k) => Artifact.validateKind(k));
+                const result = { artifacts: Artifact.list(this.log, kinds) };
+                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: `ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("ase_artifact_name", {
+            title: "ASE artifact name",
+            description: "Resolve a base-relative `filename` within an artifact `kind` to a project-relative path " +
+                "by prefixing it with the kind's configured `basedir`. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, and `infr` " +
+                "(the implicit `othr` catch-all has no basedir and is rejected). " +
+                "If `kind` is omitted, it defaults to `code`. " +
+                "Returns the resolved path as `name`.",
+            inputSchema: {
+                kind: z.string().optional()
+                    .describe("artifact kind (`spec`, `arch`, `code`, `docs`, `infr`); defaults to `code`"),
+                filename: z.string()
+                    .describe("base-relative filename within the kind's basedir")
+            },
+            outputSchema: {
+                name: z.string().describe("project-relative file path")
+            }
+        }, async (args) => {
+            try {
+                const kind = Artifact.validateKind(args.kind ?? "code");
+                const result = { name: Artifact.name(this.log, kind, args.filename) };
+                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: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-config.js

@@ -25,29 +25,41 @@ export const agentClassification = {
 /*  classification presets  */
 export const projectClassificationPresets = {
     vibe: {
+        "agent.persona": "writer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "black",
-        "agent.persona": "writer"
+        "project.boxing": "black"
     },
     pro: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "white",
-        "agent.persona": "engineer"
+        "project.boxing": "white"
     },
     default: {
+        "agent.task": "default",
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
         "project.boxing": "white",
-        "agent.persona": "engineer",
-        "agent.task": "default"
+        "project.artifact.task.basedir": ".ase/task",
+        "project.artifact.task.files": "*.md",
+        "project.artifact.spec.basedir": "doc/spec",
+        "project.artifact.spec.files": "*.{md,txt}",
+        "project.artifact.arch.basedir": "doc/arch",
+        "project.artifact.arch.files": "*.{md,txt}",
+        "project.artifact.code.basedir": "src",
+        "project.artifact.code.files": "** !**/etc/** !**/{.gitignore,.npmignore,package.json}",
+        "project.artifact.docs.basedir": "doc",
+        "project.artifact.docs.files": "** **/{README,LICENSE,CHANGELOG}.{md,txt} !{spec,arch}/**",
+        "project.artifact.infr.basedir": "",
+        "project.artifact.infr.files": "**/{.github,.claude*,etc}/** **/{AGENTS.md,{package,tsconfig*}.json,.{git,npm}ignore}"
     },
     industry: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "grey",
-        "agent.persona": "engineer"
+        "project.boxing": "grey"
     }
 };
 /*  hard-coded map: which scope kinds each variable may be SET on
@@ -55,7 +67,19 @@ export const projectClassificationPresets = {
     keys absent from this map default to all non-"default" scope kinds  */
 export const configWritableScopes = {
     "agent.task": ["session"],
-    "agent.skill": ["session"]
+    "agent.skill": ["session"],
+    "project.artifact.task.basedir": ["user", "project"],
+    "project.artifact.task.files": ["user", "project"],
+    "project.artifact.spec.basedir": ["user", "project"],
+    "project.artifact.spec.files": ["user", "project"],
+    "project.artifact.arch.basedir": ["user", "project"],
+    "project.artifact.arch.files": ["user", "project"],
+    "project.artifact.code.basedir": ["user", "project"],
+    "project.artifact.code.files": ["user", "project"],
+    "project.artifact.docs.basedir": ["user", "project"],
+    "project.artifact.docs.files": ["user", "project"],
+    "project.artifact.infr.basedir": ["user", "project"],
+    "project.artifact.infr.files": ["user", "project"]
 };
 /*  default set of scope kinds writable for any unrestricted key  */
 const configWritableScopesDefault = ["user", "project", "task", "session"];
@@ -130,7 +154,15 @@ export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
         id: v.optional(v.pipe(v.string(), v.minLength(1))),
         name: v.optional(v.pipe(v.string(), v.minLength(1))),
-        boxing: v.optional(v.picklist(projectClassification.boxing))
+        boxing: v.optional(v.picklist(projectClassification.boxing)),
+        artifact: v.optional(v.strictObject({
+            spec: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            arch: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            code: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            docs: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            infr: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            task: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) }))
+        }))
     })),
     agent: v.optional(v.strictObject({
         persona: v.optional(v.picklist(agentClassification.persona)),
@@ -614,6 +646,20 @@ export default class ConfigCommand {
                 cfg.write();
             });
         });
+        /*  register CLI sub-command "ase config delete"  */
+        configCmd
+            .command("delete")
+            .description("delete the value at a dotted configuration key")
+            .argument("<key>", "configuration key (dotted path)")
+            .action((key, _opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
+            const cfg = new Config("config", configSchema, this.log, scope);
+            cfg.lock(() => {
+                cfg.read();
+                cfg.delete(key);
+                cfg.write();
+            });
+        });
     }
 }
 /*  MCP registration entry point for layered YAML configuration access  */

package/dst/ase-service.js

@@ -18,6 +18,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { Config, configSchema, ConfigMCP } from "./ase-config.js";
 import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
+import { ArtifactMCP } from "./ase-artifact.js";
 import { KVMCP } from "./ase-kv.js";
 import PersonaMCP from "./ase-persona.js";
 import { TimestampMCP } from "./ase-timestamp.js";
@@ -236,6 +237,7 @@ export default class ServiceCommand {
             new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
             new DiagramMCP().register(mcp);
             new TaskMCP(this.log).register(mcp);
+            new ArtifactMCP(this.log).register(mcp);
             new KVMCP().register(mcp);
             new PersonaMCP(this.log).register(mcp);
             new TimestampMCP().register(mcp);