@rse/ase 2.0.5 → 2.0.7

package/dst/ase-spec.js

@@ -16,22 +16,33 @@ import { configSchema } from "./ase-config-schema.js";
 import { Task } from "./ase-task.js";
 import { Artifact } from "./ase-artifact.js";
 import { writeStdout } from "./ase-lib-stdio.js";
-/*  reusable functionality: initialize, lint, export, and preview the
+/*  reusable functionality: initialize, lint, export, query, and preview the
     SpecBook-based project specification, located via the
     "project.artifact.spec.basedir" and "project.artifact.spec.schema"
     configuration  */
 export class Spec {
-    /*  the SpecBook export formats, mirrored here (and checked for completeness
+    /*  the SpecBook export and query formats, mirrored here (and checked for completeness
         against SpecBook at compile-time) to not load SpecBook for the MCP schema  */
     static formats = Object.keys({
         json: true, json5: true, yaml: true, toon: true, html: true, pdf: true, md: true
     });
+    static queryFormats = Object.keys({
+        json: true, json5: true, yaml: true, toon: true
+    });
+    /*  whether a schema configuration entry is a reference SpecBook resolves
+        itself (mirroring its internal check): the bundled "std", "meta", and
+        "pm" ones, or a remote "npm:", "github:", or "http[s]://" one  */
+    static isRemote(entry) {
+        return entry === "std" || entry === "meta" || entry === "pm"
+            || (/^(?:npm|github):|^https?:\/\//).test(entry);
+    }
     /*  resolve the YAML schema configuration files: the whitespace-separated
         entries of the configured "project.artifact.spec.schema", merged in
-        the given order, where each entry is either the literal "std" for the
-        full SpecBook standard schema (not the agent-compressed plugin meta file
-        "ase-format-specbook.yaml") or a file path relative to the project
-        root, and an unset or empty value means "std"  */
+        the given order, where each entry is either a reference SpecBook resolves
+        itself (like "std" for the full SpecBook standard schema, not the
+        agent-compressed plugin meta file "ase-format-specbook.yaml") or a file
+        path or glob pattern relative to the project root, and an unset or
+        empty value means "std"  */
     static configFiles(log) {
         const cfg = new Config("config", configSchema, log);
         cfg.read();
@@ -40,10 +51,21 @@ export class Spec {
         const entries = list.split(/\s+/).filter((entry) => entry !== "");
         if (entries.length === 0)
             entries.push("std");
-        return entries.map((entry) => entry === "std" ?
-            "std" :
+        return entries.map((entry) => Spec.isRemote(entry) ?
+            entry :
             path.resolve(Task.projectRoot(), entry));
     }
+    /*  the source options of the reading commands: the specification below
+        the "spec" artifact base directory, or, under "schema", the effective
+        schema configuration itself (to which no base directory applies)  */
+    static source(log, schema) {
+        return {
+            config: Spec.configFiles(log),
+            basedir: schema ? undefined : Artifact.basedir(log, "spec"),
+            gitignore: Spec.gitignore,
+            schema
+        };
+    }
     /*  the ASE log level each SpecBook verbosity level maps onto: the
         "none" level carries the messages a bare SpecBook CLI run always
         prints -- the environment notices plus the lifecycle and failure
@@ -104,15 +126,17 @@ export class Spec {
     /*  initialize the absent artifact files of the schema configuration below
         the "spec" artifact base directory, letting SpecBook persist its project
         options file ".specbook.yaml" into a throw-away working directory, as
-        ASE keeps these options in its own configuration  */
-    static async init(log) {
+        ASE keeps these options in its own configuration, where "sample"
+        scaffolds one sample object per allowed object kind into the files  */
+    static async init(log, sample = false) {
         const basedir = Artifact.basedir(log, "spec");
         const cwd = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ase-spec-"));
         try {
             const result = await Spec.unmarked(Spec.api(log).then((api) => api.init({
                 config: Spec.configFiles(log),
                 basedir,
-                cwd
+                cwd,
+                sample
             })));
             return result.files.map((file) => Spec.relativize(path.join(basedir, file)));
         }
@@ -196,38 +220,46 @@ export class Spec {
         });
     }
     /*  export the specification Markdown files below the "spec" artifact
-        base directory into the requested formats, one buffer per format,
-        collecting the emitted environment notices if requested  */
-    static export(log, formats, notices) {
-        return Spec.unmarked(Spec.api(log, notices).then((api) => api.export({
-            config: Spec.configFiles(log),
-            basedir: Artifact.basedir(log, "spec"),
-            gitignore: Spec.gitignore,
-            formats
+        base directory into the requested formats, one buffer per format  */
+    static export(log, formats, options = {}) {
+        return Spec.unmarked(Spec.api(log, options.notices).then((api) => api.export({
+            ...Spec.source(log, options.schema ?? false),
+            formats,
+            rebase: options.rebase
         })));
     }
     /*  export the specification like "export" and then keep the export
         in sync with its sources, handing every fresh set of buffers to
         "onExport", where "outputs" names the files "onExport" writes,
         so an output which is itself an observed source can be refused  */
-    static watch(log, formats, outputs, onExport) {
-        return Spec.unmarked(Spec.api(log).then((api) => api.watch({
-            config: Spec.configFiles(log),
-            basedir: Artifact.basedir(log, "spec"),
-            gitignore: Spec.gitignore,
+    static watch(log, formats, outputs, onExport, options = {}) {
+        return Spec.unmarked(Spec.api(log, options.notices).then((api) => api.watch({
+            ...Spec.source(log, options.schema ?? false),
             formats,
+            rebase: options.rebase,
             outputs,
             onExport
         })));
     }
-    /*  serve the HTML export of the specification as a live preview,
-        kept in sync with its sources and pushed into the connected
-        browsers as an in-place document update  */
-    static preview(log, addr, port) {
+    /*  query the specification Markdown files below the "spec" artifact
+        base directory (or, under "schema", the effective schema configuration)
+        with an ASTq selector and its "{name}" parameters, rendering the matched
+        nodes in a serialization format and collecting the emitted notices
+        (like the lint warnings) if requested  */
+    static query(log, selector, params, format, notices, schema = false) {
+        return Spec.unmarked(Spec.api(log, notices).then(async (api) => {
+            const { renderNodes } = await import("@rse/specbook");
+            const document = await api.load(Spec.source(log, schema));
+            return renderNodes(document.query(selector, params), format);
+        }));
+    }
+    /*  serve the HTML export of the specification (or, under "schema", of
+        the effective schema configuration) as a live preview, kept in sync
+        with its sources and pushed into the connected browsers as an
+        in-place document update  */
+    static preview(log, addr, port, schema = false) {
         return Spec.unmarked(Spec.api(log).then((api) => api.preview({
-            config: Spec.configFiles(log),
-            basedir: Artifact.basedir(log, "spec"),
-            gitignore: Spec.gitignore,
+            ...Spec.source(log, schema),
             addr,
             port
         })));
@@ -244,7 +276,7 @@ export default class SpecCommand {
         /*  register CLI top-level command "ase spec"  */
         const spec = program
             .command("spec")
-            .description("Initialize, lint, export, and preview the SpecBook-based project specification")
+            .description("Initialize, lint, export, query, and preview the SpecBook-based project specification")
             .action(() => {
             spec.outputHelp();
             process.exit(1);
@@ -253,8 +285,9 @@ export default class SpecCommand {
         spec
             .command("init")
             .description("Initialize the absent specification Markdown files of the SpecBook schema configuration")
-            .action(async () => {
-            const files = await Spec.init(this.log);
+            .option("-s, --sample", "scaffold one sample object per allowed object kind into the created files")
+            .action(async (opts) => {
+            const files = await Spec.init(this.log, opts.sample === true);
             await writeStdout(files.length > 0 ?
                 `initialized artifact file(s): ${files.join(", ")}\n` :
                 "no artifact files were created\n");
@@ -286,36 +319,75 @@ export default class SpecCommand {
             .description("Export the specification Markdown files as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
             .option("-o, --output <[format:]file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
             "from the filename extension unless explicitly prefixed " +
-            "(default: \"index.html\" inside the specification base directory)", (value, previous) => previous.concat(value), new Array())
+            "(default: \"index.html\", resp. \"schema.html\" under \"--schema\", " +
+            "inside the specification base directory)", (value, previous) => previous.concat(value), new Array())
             .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change")
+            .option("-S, --schema", "export the effective schema configuration itself instead of the specification")
             .action(async (opts) => {
             const { parseOutputSpec } = await import("@rse/specbook");
+            const schema = opts.schema === true;
             const outputs = (opts.output.length > 0 ? opts.output :
-                [path.join(Artifact.basedir(this.log, "spec"), "index.html")]).map(parseOutputSpec);
+                [path.join(Artifact.basedir(this.log, "spec"), schema ? "schema.html" : "index.html")])
+                .map(parseOutputSpec);
             /*  a re-export has to land somewhere it can be picked up again,
                 which a one-shot stdout stream cannot provide  */
             if (opts.watch === true && outputs.some(({ output }) => output === "-"))
                 throw new Error("the watch mode requires regular output files " +
                     "(\"-\" for stdout is not supported)");
-            /*  parse the input once and export each distinct format once  */
-            const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
+            /*  parse the input once and export each distinct format once, the
+                normalized Markdown once per output directory, as its image
+                references are re-based onto it (but never for stdout)  */
+            const rebaseOf = ({ format, output }) => format === "md" && output !== "-" ? path.dirname(path.resolve(output)) : undefined;
+            const keyOf = (spec) => `${spec.format}:${rebaseOf(spec) ?? ""}`;
+            const distinct = outputs.filter((spec, i) => outputs.findIndex((other) => keyOf(other) === keyOf(spec)) === i);
             const write = async (buffers) => {
-                for (const { format, output } of outputs) {
-                    const data = buffers[distinct.indexOf(format)];
-                    if (output === "-")
+                for (const spec of outputs) {
+                    const data = buffers[distinct.findIndex((other) => keyOf(other) === keyOf(spec))];
+                    if (spec.output === "-")
                         await writeStdout(data);
                     else {
-                        await fs.promises.writeFile(output, data);
-                        this.log.write("info", `spec: exported specification into "${output}" (${data.length} bytes)`);
+                        await fs.promises.writeFile(spec.output, data);
+                        this.log.write("info", `spec: exported specification into "${spec.output}" (${data.length} bytes)`);
                     }
                 }
             };
+            const formats = distinct.map(({ format }) => format);
+            const rebase = distinct.map(rebaseOf);
             if (opts.watch === true) {
-                await Spec.watch(this.log, distinct, outputs.map(({ output }) => output), write);
+                await Spec.watch(this.log, formats, outputs.map(({ output }) => output), write, { schema, rebase });
                 await new Promise(() => { });
             }
             else
-                await write(await Spec.export(this.log, distinct));
+                await write(await Spec.export(this.log, formats, { schema, rebase }));
+        });
+        /*  register CLI sub-command "ase spec query"  */
+        spec
+            .command("query")
+            .description("Query the specification Markdown files with an ASTq selector, " +
+            "writing the matched nodes as JSON, JSON5, YAML, or TOON")
+            .argument("<selector>", "ASTq selector of the nodes to write")
+            .option("-P, --param <name=value>", "value of a \"{name}\" parameter of the selector (repeatable)", (value, previous) => previous.concat(value), new Array())
+            .option("-f, --format <format>", `output format (${Spec.queryFormats.join(", ")}; ` +
+            "default: inferred from the output file like for \"export\", else json)")
+            .option("-o, --output <[format:]file>", "output file (\"-\" for stdout)", "-")
+            .option("-S, --schema", "query the effective schema configuration itself instead of the specification")
+            .action(async (selector, opts) => {
+            const { parseQueryOutput } = await import("@rse/specbook");
+            const output = parseQueryOutput(opts.output, opts.format);
+            const params = {};
+            for (const param of opts.param) {
+                const m = (/^([^=]+)=(.*)$/s).exec(param);
+                if (m === null)
+                    throw new Error(`invalid query parameter "${param}" (expected "<name>=<value>")`);
+                params[m[1]] = m[2];
+            }
+            const text = await Spec.query(this.log, selector, params, output.format, undefined, opts.schema === true);
+            if (output.output === "-")
+                await writeStdout(text);
+            else {
+                await fs.promises.writeFile(output.output, text);
+                this.log.write("info", `spec: queried specification into "${output.output}" (${Buffer.byteLength(text)} bytes)`);
+            }
         });
         /*  register CLI sub-command "ase spec preview"  */
         spec
@@ -323,12 +395,13 @@ export default class SpecCommand {
             .description("Serve the HTML export of the specification Markdown files as a live preview")
             .option("-a, --addr <ip-addr>", "IP address to listen on (default: SpecBook preview address)")
             .option("-p, --port <tcp-port>", "TCP port to listen on (default: SpecBook preview port)")
+            .option("-S, --schema", "preview the effective schema configuration itself instead of the specification")
             .action(async (opts) => {
             const { previewAddr, previewPort } = await import("@rse/specbook");
             const port = Number(opts.port ?? previewPort);
             if (!Number.isInteger(port) || port < 1 || port > 65535)
                 throw new Error(`invalid TCP port "${opts.port}"`);
-            await Spec.preview(this.log, opts.addr ?? previewAddr, port);
+            await Spec.preview(this.log, opts.addr ?? previewAddr, port, opts.schema === true);
             await new Promise(() => { });
         });
     }
@@ -406,12 +479,15 @@ export class SpecMCP {
                 "(PDF as a base64-encoded resource). The export fails on any lint diagnostic. " +
                 "The `notices` array carries the environment notices emitted during the export " +
                 "(like a PDF rendering falling back onto a system-installed browser), which are " +
-                "worth reporting to the user verbatim.",
+                "worth reporting to the user verbatim. With `schema`, the effective SpecBook YAML " +
+                "schema configuration itself is exported instead, as a SpecBook document.",
             inputSchema: {
                 format: z.enum(Spec.formats).optional()
                     .describe("output format (default: inferred from the `output` file extension, else `json`)"),
                 output: z.string().optional()
-                    .describe("output file path (\"-\" or omitted returns the result directly)")
+                    .describe("output file path (\"-\" or omitted returns the result directly)"),
+                schema: z.boolean().optional()
+                    .describe("if true, export the effective schema configuration instead of the specification (default: false)")
             },
             outputSchema: {
                 notices: z.array(z.string())
@@ -426,7 +502,11 @@ export class SpecMCP {
                 const spec = args.format !== undefined || args.output === undefined ?
                     { format: args.format ?? "json", output: args.output } :
                     parseOutputSpec(args.output);
-                const [data] = await Spec.export(this.log, [spec.format], notices);
+                /*  the image references of the normalized Markdown are re-based
+                    onto the directory of the output file  */
+                const rebase = spec.format === "md" && spec.output !== undefined && spec.output !== "-" ?
+                    path.dirname(path.resolve(Task.projectRoot(), spec.output)) : undefined;
+                const [data] = await Spec.export(this.log, [spec.format], { notices, schema: args.schema ?? false, rebase: [rebase] });
                 if (spec.output !== undefined && spec.output !== "-") {
                     await fs.promises.writeFile(path.resolve(Task.projectRoot(), spec.output), data);
                     return {
@@ -452,5 +532,60 @@ export class SpecMCP {
                 return mcpToolError(err);
             }
         });
+        mcp.registerTool("ase_specbook_query", {
+            title: "ASE SpecBook query",
+            description: "Query the SpecBook specification Markdown files of the project (located via the " +
+                "`project.artifact.spec.basedir` configuration), strictly validated like for the export, " +
+                "with an XPath-like ASTq `selector` (like `// USE-CASE [ @STATUS == 'Done' ]`). " +
+                "The root node is of type `specification`, its children are of type `artifact` (attributes " +
+                "`created`, `modified`, and `file`), and the objects below are typed by their kind, with " +
+                "whitespace dashed (attributes `kind`, `id`, `anchor`, `paren`, `name`, `primary`, " +
+                "`description`, `rationale`, `elaboration`, and one per property key), where the query " +
+                "function `refs()` yields the objects the references of an object resolve to. A `{name}` " +
+                "in the selector is substituted by the corresponding entry of `params`. The matched nodes " +
+                "are rendered as a JSON (or JSON5, YAML, or TOON) array (their subtrees included, the " +
+                "embedded file contents dropped), written to the `output` file (a relative path resolves " +
+                "against the project root) if given, else returned directly. With `schema`, the effective " +
+                "SpecBook YAML schema configuration itself is queried instead, as a SpecBook document of " +
+                "the bundled meta schema configuration. The `notices` array carries the messages emitted " +
+                "during the loading (like the warning diagnostics of the specification).",
+            inputSchema: {
+                selector: z.string()
+                    .describe("ASTq selector of the nodes to return"),
+                params: z.record(z.string(), z.string()).optional()
+                    .describe("values of the `{name}` parameters of the selector (default: none)"),
+                format: z.enum(Spec.queryFormats).optional()
+                    .describe("output format (default: inferred from the `output` file extension, else `json`)"),
+                output: z.string().optional()
+                    .describe("output file path (\"-\" or omitted returns the result directly)"),
+                schema: z.boolean().optional()
+                    .describe("if true, query the effective schema configuration instead of the specification (default: false)")
+            },
+            outputSchema: {
+                notices: z.array(z.string())
+                    .describe("messages emitted during the loading, empty if there were none")
+            }
+        }, async (args) => {
+            const notices = new Array();
+            try {
+                const { parseQueryOutput } = await import("@rse/specbook");
+                const spec = parseQueryOutput(args.output ?? "-", args.format);
+                const text = await Spec.query(this.log, args.selector, args.params ?? {}, spec.format, notices, args.schema ?? false);
+                if (spec.output !== "-") {
+                    await fs.promises.writeFile(path.resolve(Task.projectRoot(), spec.output), text);
+                    return {
+                        structuredContent: { notices },
+                        content: [{ type: "text", text: `queried specification into "${spec.output}" (${Buffer.byteLength(text)} bytes)` }]
+                    };
+                }
+                return {
+                    structuredContent: { notices },
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
     }
 }

package/dst/ase-task-board-tui-model.js

@@ -947,7 +947,8 @@ export const useBoardState = (log, initial, relay) => {
     const viewW = innerW - 4;
     let { x, y } = scroll;
     const box = view === "graph" ? places.get(sel.id) : view === "flow" ? flowPlaces.get(flowSel) : undefined;
-    const height = view === "graph" ? layout?.graph.height : flowLayout?.graph.height;
+    const graph = view === "graph" ? layout?.graph : view === "flow" ? flowLayout?.graph : undefined;
+    const height = graph?.height;
     const follow = `${view}:${flowSel}`;
     if (box !== undefined && height !== undefined && (view !== "flow" || followed.current !== follow)) {
         const top = Math.max(0, box.top - 2);
@@ -965,6 +966,12 @@ export const useBoardState = (log, initial, relay) => {
     }
     if (view !== "flow")
         followed.current = "";
+    /*  keep the viewport within the bounds of the shown graph, as the scroll position is shared
+        by both graphs (and else, a position carried over from the other one may show only its tail)  */
+    if (graph !== undefined) {
+        x = Math.max(0, Math.min(Math.max(0, graph.width + 2 - viewW), x));
+        y = Math.max(0, Math.min(Math.max(0, graph.height + 1 - viewH), y));
+    }
     if (x !== scroll.x || y !== scroll.y)
         setScroll({ x, y });
     /*  scroll the viewport of the agent graph freely (within its bounds)  */

package/dst/ase-task-board-tui.js

@@ -5,6 +5,7 @@
 */
 import React from "react";
 import { render, Box, Text, useInput, useStdin } from "ink";
+import stringWidth from "string-width";
 import { Task } from "./ase-task.js";
 import { buildBoard, toneOf, viewLabels } from "./ase-task-board-core.js";
 import pkg from "../package.json" with { type: "json" };
@@ -160,6 +161,25 @@ const App = ({ log, initial, project, relay }) => {
     });
     return renderScreen(ctx, project);
 };
+/*  wrap stdout to erase the tail of each changed line ("CSI <n> G" plus "CSI K" plus
+    its styled text) after instead of before its text, as otherwise the line is shown
+    blanked in terminals redrawing between the reads of a frame, like tmux popups;
+    a text reaching the last column needs no erasing, which would there erase its
+    last character, as the cursor rests on it  */
+const lateErasing = (stream) => {
+    /*  eslint-disable-next-line no-control-regex  */
+    const changed = /\x1b\[(\d+)G\x1b\[K((?:[^\x1b\n]|\x1b\[[\d;:]*m)*)/g;
+    const write = (data, ...args) => stream.write(typeof data !== "string" ? data :
+        data.replace(changed, (_all, col, text) => `\x1b[${col}G${text}` + (Number(col) - 1 + stringWidth(text) < stream.columns ? "\x1b[K" : "")), ...args);
+    return new Proxy(stream, {
+        get: (target, prop) => {
+            if (prop === "write")
+                return write;
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        }
+    });
+};
 /*  run the terminal board until the user quits  */
 export const runTUI = async (log, relay) => {
     const initial = await buildBoard(log);
@@ -175,9 +195,13 @@ export const runTUI = async (log, relay) => {
     process.once("exit", reset);
     try {
         /*  enable the kitty keyboard protocol (if the terminal supports it),
-            as only under it the Shift modifier of RETURN is reported  */
+            as only under it the Shift modifier of RETURN is reported, and
+            rewrite only the changed lines of a frame, as otherwise every frame
+            is erased and redrawn entirely, which flickers in terminals not
+            honoring synchronized output (DEC mode 2026), like tmux popups  */
         const app = render(h(App, { log, initial, project, relay }), {
-            alternateScreen: true, exitOnCtrlC: true, patchConsole: true, kittyKeyboard: { mode: "auto" }
+            alternateScreen: true, exitOnCtrlC: true, patchConsole: true, kittyKeyboard: { mode: "auto" },
+            incrementalRendering: true, stdout: lateErasing(process.stdout)
         });
         await app.waitUntilExit();
     }