@rse/ase 2.0.4 → 2.0.6

package/dst/ase-config-schema.js

@@ -61,7 +61,7 @@ export const projectClassificationPresets = {
         "project.task.effort.line": "0.025",
         "project.task.effort.iteration": "2.5",
         "project.artifact.spec.basedir": "docs/specbook",
-        "project.artifact.spec.files": "*.{md,txt,svg,png,jpg}",
+        "project.artifact.spec.files": "**/*.{md,txt,svg,png,jpg}",
         "project.artifact.spec.schema": "",
         "project.artifact.code.basedir": "src",
         "project.artifact.code.files": "** !**/etc/** !**/{.gitignore,.npmignore,package.json}",

package/dst/ase-hook.js

@@ -462,7 +462,8 @@ export default class HookCommand {
             guaranteed to appear once in every non-headless session;
             Anthropic Claude Code CLI and OpenAI Codex CLI surface a top-level
             "systemMessage" field for this -- GitHub Copilot CLI has no equivalent);
-            the trailing help hint is emitted only if the guidance level asks for it  */
+            the trailing help hints are emitted only if the guidance level asks for them,
+            and the inline ones only for Anthropic Claude Code CLI, which alone runs the mods  */
         const banner = "\n" +
             `\n⧉ ASE: ⎈ version: ${version}${versionHint !== "" ? " " + versionHint.replace(/\*/g, "") : ""}` +
             `\n⧉ ASE: ※ user: ${userId}, ⚑ project: ${projectId}` +
@@ -470,8 +471,16 @@ export default class HookCommand {
             `\n⧉ ASE: ☯ persona: ${persona}, ▶ guidance: ${guidance}, ▢ boxing: ${boxing}` +
             (guidance === "normal" || guidance === "verbose" ?
                 "\n" +
-                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent-description>\" for skill command proposals" +
-                    "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill-name>]\" for skill catalog or skill manpage" : "");
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent>\" for conversational skill command proposals" +
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill>]\" for conversational skill catalog or manpage lookup" +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"<intent> !!\" for inline skill command proposals" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"/<skill> !!\" for inline skill command composition" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"/<skill> //\" for inline skill manpage lookup" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"[<filter>] //\" for inline skill manpage browsing" : "") : "");
         /*  inject markdown into session context.
             Anthropic Claude Code CLI and OpenAI Codex CLI expect the context nested in
             "hookSpecificOutput"; GitHub Copilot CLI expects a flat top-level

package/dst/ase-setup-settings.js

@@ -11,7 +11,7 @@ import { mkdirp } from "mkdirp";
 import JsonAsty from "json-asty";
 import { toolSpecs } from "./ase-setup-common.js";
 import { telemetryEndpoint, telemetryEnabled } from "./ase-service-otel.js";
-/*  settings file handling of "ase setup statusline", "ase setup telemetry", and the output style  */
+/*  settings file handling of "ase setup statusline", "ase setup telemetry", the output style, and the function hooks  */
 export class SetupSettings {
     log;
     constructor(log) {
@@ -358,6 +358,116 @@ export class SetupSettings {
         }
         return entries;
     }
+    /*  the environment variable enabling the function hooks of the plugin-shipped mods
+        (Anthropic Claude Code CLI only, as the other tools have no function hooks concept)  */
+    functionHooksVar = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
+    /*  determine the value of the function hooks variable in an "env" object  */
+    functionHooksValue(env) {
+        const val = this.settingsFindMember(env, this.functionHooksVar)?.query("/ * [ pos() == 2 ]")[0];
+        return val !== undefined ? String(val.get("value") ?? "") : undefined;
+    }
+    /*  enable the function hooks of the plugin-shipped mods by setting their
+        variable in the "env" of the settings file of the scope  */
+    async functionHooksActivate(action, scope) {
+        const file = this.settingsFile("claude", scope);
+        const root = await this.settingsReadAst(file);
+        /*  reject a non-object "env" member  */
+        let member = this.settingsFindMember(root, "env");
+        let env = member?.query("/ * [ pos() == 2 ]")[0];
+        if (member !== undefined && (env === undefined || env.type() !== "object")) {
+            this.log.write("warning", `setup: ${action}: a non-object "env" ` +
+                `is present in ${file}: preserving it (skipped)`);
+            return;
+        }
+        /*  leave an ASE variable as is and preserve a foreign value: skip and warn  */
+        const value = env !== undefined ? this.functionHooksValue(env) : undefined;
+        if (value !== undefined) {
+            if (value !== "1")
+                this.log.write("warning", `setup: ${action}: a non-ASE "${this.functionHooksVar}" ` +
+                    `is already present in "env" of ${file}: preserving it (skipped)`);
+            return;
+        }
+        /*  insert a fresh (still empty) "env" member  */
+        if (member === undefined || env === undefined) {
+            env = root.create("object").set({ prolog: "{", epilog: "}" });
+            member = root.create("member").add(root.create("string").set({ body: JSON.stringify("env"), value: "env", epilog: ": " }), env);
+            this.settingsAddMember(root, member, false);
+        }
+        /*  add the variable  */
+        const key = root.create("string").set({
+            body: JSON.stringify(this.functionHooksVar),
+            value: this.functionHooksVar,
+            epilog: ": "
+        });
+        const val = root.create("string").set({ body: JSON.stringify("1"), value: "1" });
+        env.add(root.create("member").add(key, val));
+        this.settingsNormalizeObject(env, 1, this.settingsTrailing(root, member));
+        await this.settingsWriteAst(file, root);
+        this.log.write("info", `setup: ${action}: enabling function hooks in "env" of ${file}`);
+    }
+    /*  disable the function hooks of the plugin-shipped mods by removing
+        their variable from the "env" of the settings file of the scope  */
+    async functionHooksDeactivate(action, scope) {
+        const file = this.settingsFile("claude", scope);
+        /*  a missing settings file means nothing to remove  */
+        try {
+            await fs.access(file);
+        }
+        catch {
+            return;
+        }
+        const root = await this.settingsReadAst(file);
+        const member = this.settingsFindMember(root, "env");
+        const env = member?.query("/ * [ pos() == 2 ]")[0];
+        if (member === undefined || env === undefined || env.type() !== "object")
+            return;
+        const target = this.settingsFindMember(env, this.functionHooksVar);
+        if (target === undefined)
+            return;
+        /*  preserve a foreign value: skip and warn  */
+        if (this.functionHooksValue(env) !== "1") {
+            this.log.write("warning", `setup: ${action}: a non-ASE "${this.functionHooksVar}" ` +
+                `is present in "env" of ${file}: preserving it (skipped)`);
+            return;
+        }
+        /*  remove the variable and, if it became empty, the "env" member  */
+        env.del(target);
+        if (env.query("/ member").length === 0)
+            this.settingsRemoveMember(root, member);
+        else
+            this.settingsNormalizeObject(env, 1, this.settingsTrailing(root, member));
+        await this.settingsWriteAst(file, root);
+        this.log.write("info", `setup: ${action}: disabling function hooks in "env" of ${file}`);
+    }
+    /*  probe the function hooks variables by inspecting the tool
+        settings files of all installation scopes (Anthropic Claude Code CLI only)  */
+    async functionHooksStatus(tool) {
+        if (tool !== "claude")
+            return [];
+        const scopes = ["user", "project", "local"];
+        const entries = [];
+        for (const scope of scopes) {
+            const file = this.settingsFile(tool, scope);
+            let root;
+            try {
+                root = await this.settingsReadAst(file);
+            }
+            catch {
+                /*  an unparsable settings file carries no usable state  */
+                continue;
+            }
+            const env = this.settingsFindMember(root, "env")?.query("/ * [ pos() == 2 ]")[0];
+            const value = env !== undefined && env.type() === "object" ? this.functionHooksValue(env) : undefined;
+            if (value === undefined)
+                continue;
+            entries.push({
+                file: this.fileDisplay(file),
+                scope,
+                status: value === "1" ? "enabled" : "foreign"
+            });
+        }
+        return entries;
+    }
     /*  auto-detect the scope in which the ASE plugin is currently
         installed, so an omitted --scope targets the existing installation
         instead of blindly assuming the per-user scope; only the Anthropic

package/dst/ase-setup.js

@@ -38,9 +38,12 @@ export default class SetupCommand {
         const scopeArgs = tool === "claude" && scope !== "user" ? ["--scope", scope] : [];
         await this.runner.run(spec.cli, ["plugin", "marketplace", "add", source, ...scopeArgs]);
         await this.runner.run(spec.cli, ["plugin", spec.pInstall, "ase@ase", ...scopeArgs], { retries: 3 });
-        /*  select the plugin-shipped ASE output style (Anthropic Claude Code CLI only)  */
-        if (tool === "claude")
+        /*  select the plugin-shipped ASE output style and enable the function
+            hooks of the plugin-shipped mods (Anthropic Claude Code CLI only)  */
+        if (tool === "claude") {
             await this.settings.outputStyleActivate(`install${dev ? "[dev]" : ""}`, scope);
+            await this.settings.functionHooksActivate(`install${dev ? "[dev]" : ""}`, scope);
+        }
         return 0;
     }
     /*  handler for "ase setup update" (all tools)  */
@@ -97,9 +100,12 @@ export default class SetupCommand {
                 await this.runner.run(spec.cli, ["plugin", spec.pInstall, "ase@ase", ...scopeArgs], { retries: 3 });
             }
         }
-        /*  select the plugin-shipped ASE output style (Anthropic Claude Code CLI only)  */
-        if (tool === "claude")
+        /*  select the plugin-shipped ASE output style and enable the function
+            hooks of the plugin-shipped mods (Anthropic Claude Code CLI only)  */
+        if (tool === "claude") {
             await this.settings.outputStyleActivate(`update${dev ? "[dev]" : ""}`, scope);
+            await this.settings.functionHooksActivate(`update${dev ? "[dev]" : ""}`, scope);
+        }
         return 0;
     }
     /*  handler for "ase setup enable|disable" (all tools)  */
@@ -130,9 +136,12 @@ export default class SetupCommand {
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             "stopping potentially running ASE service");
         await this.runner.run("ase", ["service", "stop"], { quiet: true, ignoreError: "ASE service not running" });
-        /*  deselect the plugin-shipped ASE output style (Anthropic Claude Code CLI only)  */
-        if (tool === "claude")
+        /*  deselect the plugin-shipped ASE output style and disable the function
+            hooks of the plugin-shipped mods (Anthropic Claude Code CLI only)  */
+        if (tool === "claude") {
             await this.settings.outputStyleDeactivate(`uninstall${dev ? "[dev]" : ""}`, scope);
+            await this.settings.functionHooksDeactivate(`uninstall${dev ? "[dev]" : ""}`, scope);
+        }
         /*  uninstall ASE plugin  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             `uninstalling ASE ${spec.label} plugin (origin: ${dev ? "local" : "remote/bundled"})`);
@@ -172,6 +181,9 @@ export default class SetupCommand {
         /*  report the ASE output style selections  */
         for (const outputStyle of await this.settings.outputStyleStatus(tool))
             rows.push(["OUTPUTSTYLE", chalk.bold(outputStyle.file), outputStyle.scope, outputStyle.status]);
+        /*  report the function hooks enablements  */
+        for (const functionHooks of await this.settings.functionHooksStatus(tool))
+            rows.push(["FUNCTIONHOOKS", chalk.bold(functionHooks.file), functionHooks.scope, functionHooks.status]);
         /*  report the ASE statusline registrations  */
         for (const statusline of await this.settings.statuslineStatus(tool))
             rows.push(["STATUSLINE", chalk.bold(statusline.file), statusline.scope, statusline.status]);
@@ -307,7 +319,7 @@ export default class SetupCommand {
         /*  register CLI sub-command "ase setup status"  */
         setupCmd
             .command("status")
-            .description("report the ASE plugin, MCP server, output style, statusline, and telemetry registrations for a tool")
+            .description("report the ASE plugin, MCP server, output style, function hooks, statusline, and telemetry registrations for a tool")
             .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (opts) => {
             process.exit(await this.doStatus(parseTool(opts.tool)));

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)  */