@rse/specbook 1.6.0 → 1.6.1

package/README.md

@@ -25,7 +25,8 @@ format* which can be configured for the specifications of particular
 contexts through a YAML-based *schema configuration*. SpecBook allows
 specifications to be *initialized*, *linted*, *exported* (JSON, JSON5,
 YAML, TOON, HTML, PDF, and normalized Markdown), *previewed* (HTML, live
-in the browser), and *described* to LLMs.
+in the browser), *queried* (ASTq selectors on the AST), and *described*
+to LLMs.
 
 **SpecBook** ships with an API class with methods `<xxx>()`, a
 CLI with commands `specbook <xxx>`, and an MCP service with tools
@@ -168,10 +169,9 @@ $ specbook export \
   [-F|--fetch <mode>] \
   [-g|--gitignore] \
   [-S|--schema] \
-  [-o|--output [<format>:]<output-file>] \
+  [-o|--output [<format>:]<output-file>] [...] \
   [-w|--watch] \
-  [-O|--omit <aspect>[,...]] \
-  [...]
+  [-O|--omit <aspect>[,...]]
 
 $ specbook preview \
   [-v|--verbose [<level>]] \
@@ -184,6 +184,18 @@ $ specbook preview \
   [-a|--addr <ip-addr>] \
   [-p|--port <tcp-port>]
 
+$ specbook query \
+  [-v|--verbose [<level>]] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-F|--fetch <mode>] \
+  [-g|--gitignore] \
+  [-S|--schema] \
+  [-P|--param <name>=<value>] [...] \
+  [-f|--format <format>] \
+  [-o|--output [<format>:]<output-file>] \
+  <selector>
+
 $ specbook describe \
   [-v|--verbose [<level>]] \
   [-c|--config <schema-yaml-file>] \
@@ -266,7 +278,7 @@ Options:
     whenever the download cache lacks a reference or it is no longer
     fresh), or `always` (ignoring the download cache).
 
--   `-g|--gitignore` (`lint`, `export`, and `preview` only):
+-   `-g|--gitignore` (`lint`, `export`, `preview`, and `query` only):
     Set aside every specification file the Git exclude rules (the global
     excludes file, the repository-local `info/exclude`, and the
     `.gitignore` files, with Git's own precedence) exclude from its
@@ -274,8 +286,8 @@ Options:
     artifacts are optional, else as the error `artifact file excluded by
     Git`. A base directory outside any Git working tree excludes nothing.
 
--   `-S|--schema` (`export` and `preview` only):
-    Export (or preview) the *effective schema configuration itself* --
+-   `-S|--schema` (`export`, `preview`, and `query` only):
+    Export (or preview, or query) the *effective schema configuration itself* --
     the one `-c|--config` selects, merged out of its local, bundled, or
     remote files -- as a SpecBook document, instead of the specification
     below the base directory (which is not applicable then, so an
@@ -357,6 +369,28 @@ Options:
     the connection state: its plug icon carries the search highlight
     color while disconnected and blinks for 2s after every update.
 
+-   `-P|--param <name>=<value>`, `<selector>` (`query` only):
+    Query the specification (strictly validated like `export`) with the
+    XPath-like selector of [ASTq](https://github.com/rse/astq) and write
+    the matched nodes as an array (their subtrees included, the embedded
+    file contents dropped), where `-P|--param` (repeatable) gives the
+    value of a `{name}` parameter of the selector.
+    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 (attributes `kind`, `id`,
+    `anchor`, `paren`, `name`, `primary`, `description`, `rationale`,
+    `elaboration`, and one per property key), e.g.
+    `specbook query "// USE-CASE [ @ACTOR == '[[ROLE:attendee]]' ]"`. The
+    query function `refs()` yields the objects the references of an object
+    resolve to, e.g. `specbook query "// REQUIREMENT [ count(refs()) == 0 ]"`.
+
+-   `-f|--format <format>`, `-o|--output [<format>:]<output-file>` (`query` only):
+    The output file (default: `-` for stdout) receives the matched nodes
+    in the format `json`, `json5`, `yaml`, or `toon`, where an explicit
+    `-f|--format` wins and the format is otherwise inferred exactly like
+    for an `export` output (a `<format>:` prefix, else the filename
+    extension, while plain `-` defaults to JSON).
+
 -   `-o|--output <output-file>` (`describe` only):
     The output file (default: `-` for stdout) receives the described
     Markdown document.
@@ -441,6 +475,41 @@ Chrome* (the equivalent of `chrome`). An explicitly configured browser
 failing to launch fails the export instead of falling back onto another
 browser.
 
+### API
+
+Third-party scripts generating foreign documents out of a specification
+load it (strictly validated like `export`) and query its AST through the
+very same ASTq selectors as `specbook query`, retrieving the *original*
+AST nodes:
+
+```ts
+import { SpecBook, type SpecObject } from "@rse/specbook"
+
+const specbook = new SpecBook()
+const document = await specbook.load({ basedir: "docs/spec" })
+
+/*  register a custom query function (beside the built-in "refs()")  */
+document.func("contains", (_adapter, _node, list, item) =>
+    Array.isArray(list) && list.includes(item))
+
+/*  emit the roles with the use cases referencing them as Markdown  */
+for (const role of document.query("// ROLE") as SpecObject[]) {
+    console.log(`## ${document.plain(role.name)}\n`)
+    for (const useCase of document.query("// USE-CASE [ contains(refs(), {role}) ]",
+        { role }) as SpecObject[])
+        console.log(`-   ${document.plain(useCase.name)}`)
+}
+```
+
+The `SpecBookDocument` returned by `load()` (options like `lint`, plus
+`schema`) carries the `specification`, its `config`, and the warning
+`diagnostics`, and provides `query(selector, params?)`, `parent(node)`
+(the AST nodes carrying no parent references), `func(name, fn)`, and the
+text helpers `plain(text, from?)` and `html(text, from?)`, which render
+a Markdown text (a description part or property value) into plain text
+resp. an HTML fragment, replacing every `[[...]]` reference by the name
+of its target object.
+
 Remote References
 -----------------
 

package/dst/specbook-api.d.ts

@@ -3,6 +3,7 @@ import { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, pa
 import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity } from "./specbook-diagnostic.js";
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, omitAspects, type ExportFormat } from "./specbook-cmd-export.js";
+import { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput, type SpecNode, type SpecQueryFunc, type SpecQueryAdapter, type QueryFormat } from "./specbook-cmd-query.js";
 import { previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel, type DescribeFormat, type DescribePart, type CompressLevel } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity, type Verbose, type VerboseLevel, type Verbosity } from "./specbook-verbose.js";
@@ -16,6 +17,7 @@ export { compressLevels, parseCompressLevel };
 export { type DescribeFormat, type DescribePart, type CompressLevel };
 export { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic, type DiagnosticSeverity };
 export { type LintResult };
+export { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput, type SpecNode, type SpecQueryFunc, type SpecQueryAdapter, type QueryFormat };
 export { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, parseFetchMode, type FetchMode, type SearchHit };
 export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } from "./specbook-format-spec.js";
 export type { Schema, SchemaObject, SchemaProperty } from "./specbook-format-schema.js";
@@ -64,6 +66,10 @@ export declare class SpecBook {
     lint(options: ProjectOptions & {
         gitignore?: boolean;
     }): Promise<LintResult>;
+    load(options: ProjectOptions & {
+        gitignore?: boolean;
+        schema?: boolean;
+    }): Promise<SpecBookDocument>;
     search(options: SearchRequest): Promise<SearchHit[]>;
     private renderFormats;
     private rebaseOf;

package/dst/specbook-api.js

@@ -13,6 +13,7 @@ import { lint } from "./specbook-cmd-lint.js";
 import { isBelow } from "./specbook-files.js";
 import { exportSpecification, watchSpecification, parseOutputSpec, formats, requireBrowser, parseOmit, omitAspects } from "./specbook-cmd-export.js";
 import { lintSchema } from "./specbook-cmd-export-schema.js";
+import { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput } from "./specbook-cmd-query.js";
 import { servePreview, previewAddr, previewPort } from "./specbook-cmd-preview.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, compressLevels, parseCompressLevel } from "./specbook-cmd-describe.js";
 import { literal, renderVerbose, verbosities, verbosityOf, parseVerbosity } from "./specbook-verbose.js";
@@ -24,6 +25,7 @@ export { projectFile };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { compressLevels, parseCompressLevel };
 export { renderDiagnostic, renderDiagnosticVerbose };
+export { SpecBookDocument, renderNodes, queryFormats, parseQueryOutput };
 export { version, standardConfig, metaConfig, pmConfig, cacheDir, fetchModes, parseFetchMode };
 /*  the SpecBook API  */
 export class SpecBook {
@@ -138,6 +140,28 @@ export class SpecBook {
         return lint({ config: await this.configFiles(project.config, this.remoteOptions(options, verbose)),
             basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
     }
+    /*  load the specification Markdown files below the base directory (or,
+        under "schema", the effective schema configuration itself, described
+        as a specification of the bundled meta schema configuration) as a
+        document queryable through ASTq selectors, strictly like "export":
+        any error diagnostic prevents the loading, as a partial or invalid
+        specification must never be consumed, while the warnings are just
+        surfaced as unconditional verbose messages  */
+    async load(options) {
+        const verbose = this.verboseOf("load");
+        if (options.schema === true && options.basedir !== undefined)
+            throw new Error("the base directory is not applicable to the export of the schema configuration");
+        const project = this.project(options, verbose);
+        const labels = new Map();
+        const config = await this.configFiles(project.config, this.remoteOptions(options, verbose), labels);
+        const result = this.parseSource(options, config, labels, project.basedir ?? ".", verbose);
+        if (result.config === undefined || result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
+            throw new Error("invalid specification:\n" +
+                result.diagnostics.map(renderDiagnostic).join("\n"));
+        for (const diagnostic of result.diagnostics)
+            verbose(renderDiagnostic(diagnostic), "none");
+        return new SpecBookDocument(result.specification, result.config, result.diagnostics, result.origins);
+    }
     /*  search the bundled schema configurations, the npm
         registry, and GitHub for the shareable schema configurations
         matching a term  */

package/dst/specbook-cli.js

@@ -8,7 +8,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command, CommanderError } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, projectFile, omitAspects, parseFetchMode, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, parseVerbosity, verbosityOf, projectFile, omitAspects, parseFetchMode, version, renderNodes, queryFormats, parseQueryOutput } from "./specbook-api.js";
 import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved for the
     command outputs and the MCP protocol, and qualify every message with
@@ -239,6 +239,34 @@ withSchemaOption(withOmitOption(withGitignoreOption(withCommonOptions(program.co
     await specbook.preview({ config: configOf(opts), basedir: opts.basedir, fetch: fetchOf(opts),
         addr: opts.addr, port, omit: omitOf(opts), gitignore: opts.gitignore, schema: opts.schema });
 });
+/*  the query command loads the specification and writes the
+    nodes an ASTq selector matches as JSON, JSON5, YAML, or TOON  */
+withSchemaOption(withGitignoreOption(withCommonOptions(program.command("query"))))
+    .description("query the specification Markdown files below the base directory " +
+    "(or the schema configuration itself) with an ASTq selector, writing the matched nodes " +
+    "as JSON, JSON5, YAML, or TOON")
+    .argument("<selector>", "the 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 (${queryFormats.join(", ")}; ` +
+    "default: inferred from the output file like for \"export\", else json)", envDefault("format"))
+    .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
+    .action(async (selector, opts) => {
+    const verbose = verboseOf(opts);
+    const output = parseQueryOutput(opts.output, opts.format);
+    const fallback = envDefault("param");
+    const given = opts.param.length > 0 ? opts.param : (fallback !== undefined ? [fallback] : []);
+    const params = {};
+    for (const param of given) {
+        const m = (/^([^=]+)=(.*)$/s).exec(param);
+        if (m === null)
+            throw new Error(`invalid query parameter "${param}" (expected "<name>=<value>")`);
+        params[m[1]] = m[2];
+    }
+    const specbook = new SpecBook({ verbose });
+    const document = await specbook.load({ config: configOf(opts), basedir: opts.basedir,
+        fetch: fetchOf(opts), gitignore: opts.gitignore, schema: opts.schema });
+    await writeOutput(output.output, renderNodes(document.query(selector, params), output.format), "query", verbose);
+});
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */
 withFetchOption(withBasedirOption(withConfigOption(withVerboseOption(program.command("describe")), "the bundled standard schema configuration, embedded"), "none"))

package/dst/specbook-cmd-query.d.ts

@@ -0,0 +1,30 @@
+import ASTQ from "astq";
+import type { Spec, SpecArtifact, SpecObject } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.js";
+import type { Diagnostic } from "./specbook-diagnostic.js";
+export type SpecNode = Spec | SpecArtifact | SpecObject;
+export type SpecQueryAdapter = ASTQ.Adapter<SpecNode>;
+export type SpecQueryFunc = (adapter: SpecQueryAdapter, node: SpecNode, ...args: unknown[]) => unknown;
+export declare const queryFormats: readonly ["json", "json5", "yaml", "toon"];
+export type QueryFormat = typeof queryFormats[number];
+export declare const parseQueryOutput: (output: string, format?: string) => {
+    format: QueryFormat;
+    output: string;
+};
+export declare const renderNodes: (nodes: SpecNode[], format?: QueryFormat) => string;
+export declare class SpecBookDocument {
+    readonly specification: Spec;
+    readonly config: Schema;
+    readonly diagnostics: Diagnostic[];
+    private astq;
+    private parents;
+    private attrs;
+    private index;
+    constructor(specification: Spec, config: Schema, diagnostics: Diagnostic[], origins: Map<SpecArtifact, string>);
+    query(selector: string, params?: Record<string, unknown>): SpecNode[];
+    parent(node: SpecNode): SpecNode | undefined;
+    func(name: string, fn: SpecQueryFunc): this;
+    private expand;
+    plain(text: string, from?: SpecObject): string;
+    html(text: string, from?: SpecObject): string;
+}

package/dst/specbook-cmd-query.js

@@ -0,0 +1,165 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import ASTQ from "astq";
+import { Marked } from "marked";
+import JSON5 from "json5";
+import { stringify as stringifyYaml } from "yaml";
+import { encode as encodeToon } from "@toon-format/toon";
+import { buildLinkIndex, referenceTargets, resolveUnique, expandReferences } from "./specbook-link.js";
+import { parseOutputSpec } from "./specbook-cmd-export.js";
+/*  the fixed attributes of an object node, which win over
+    the same-named property keys  */
+const objectFields = ["kind", "id", "anchor", "paren", "name", "primary",
+    "description", "rationale", "elaboration"];
+/*  the private Markdown renderer of the text helpers, as the
+    "marked" singleton is shared with the application  */
+const marked = new Marked();
+/*  render Markdown tokens into plain text: the blocks joined by the
+    separator, the inline markup dropped, and the code kept verbatim  */
+const plainOf = (tokens, separator) => tokens.map((generic) => {
+    const token = generic;
+    if (token.type === "space" || token.type === "hr" || token.type === "html" || token.type === "def")
+        return "";
+    else if (token.type === "code" || token.type === "codespan")
+        return token.text;
+    else if (token.type === "br")
+        return "\n";
+    else if (token.type === "blockquote")
+        return plainOf(token.tokens, "\n\n");
+    else if (token.type === "list")
+        return token.items.map((item) => plainOf(item.tokens, "\n")).join("\n");
+    else if (token.type === "table")
+        return [token.header, ...token.rows].map((row) => row.map((cell) => plainOf(cell.tokens, "")).join(" | ")).join("\n");
+    else if ("tokens" in token && token.tokens !== undefined)
+        return plainOf(token.tokens, "");
+    else
+        return "text" in token ? token.text : "";
+}).filter((part) => part !== "").join(separator);
+/*  the serialization formats of the query results (the AST export ones)  */
+export const queryFormats = ["json", "json5", "yaml", "toon"];
+/*  determine the format and file of a query output: an explicit format
+    wins, else it is inferred exactly like the one of an export output
+    (a "<format>:" prefix, else the filename extension, "-" being JSON),
+    where only the serialization formats apply  */
+export const parseQueryOutput = (output, format) => {
+    const spec = format !== undefined ? { format, output } : parseOutputSpec(output);
+    if (!queryFormats.includes(spec.format))
+        throw new Error(`unsupported query format "${spec.format}" (supported: ${queryFormats.join(", ")})`);
+    return { format: spec.format, output: spec.output };
+};
+/*  render query result nodes in a serialization format: their subtrees
+    included, the embedded file contents dropped (the bulk no consumer
+    can use), and the dates as ISO strings  */
+export const renderNodes = (nodes, format = "json") => {
+    const plain = JSON.parse(JSON.stringify(nodes, (key, value) => key === "embedding" ? undefined : value));
+    if (format === "json")
+        return JSON.stringify(plain, null, 4) + "\n";
+    else if (format === "json5")
+        return JSON5.stringify(plain, null, 4) + "\n";
+    else if (format === "yaml")
+        return stringifyYaml(plain);
+    else
+        return encodeToon(plain) + "\n";
+};
+/*  a loaded specification, queryable through the XPath-like ASTq
+    selectors: the root node (type "specification") holds the artifacts
+    (type "artifact"), which hold the object trees (typed by their kind,
+    whitespace dashed), and the pre-registered function "refs()" yields
+    the objects the references of the current object resolve to  */
+export class SpecBookDocument {
+    specification;
+    config;
+    diagnostics;
+    astq = new ASTQ();
+    parents = new WeakMap();
+    attrs = new WeakMap();
+    index;
+    constructor(specification, config, diagnostics, origins) {
+        this.specification = specification;
+        this.config = config;
+        this.diagnostics = diagnostics;
+        this.index = buildLinkIndex(specification);
+        /*  index the parents once, as the objects carry no parent reference  */
+        const walk = (object, parent) => {
+            this.parents.set(object, parent);
+            for (const child of object.children)
+                walk(child, object);
+        };
+        for (const artifact of specification.artifacts) {
+            this.parents.set(artifact, specification);
+            for (const object of artifact.objects)
+                walk(object, artifact);
+        }
+        /*  determine the attributes of a node once: the timestamps and
+            source file of an artifact, and the fixed fields of an object
+            followed by its properties (the first of duplicate keys winning)  */
+        const attributesOf = (node) => {
+            let attrs = this.attrs.get(node);
+            if (attrs === undefined) {
+                attrs = new Map();
+                if ("objects" in node) {
+                    attrs.set("created", node.created.toISOString());
+                    attrs.set("modified", node.modified.toISOString());
+                    attrs.set("file", origins.get(node));
+                }
+                else if ("kind" in node) {
+                    const fields = [node.kind, node.id, node.anchor, node.paren, node.name, node.primary,
+                        node.description?.description, node.description?.rationale, node.description?.elaboration];
+                    for (const [i, value] of fields.entries())
+                        if (value !== undefined)
+                            attrs.set(objectFields[i], value);
+                    for (const property of node.properties)
+                        if (!objectFields.includes(property.key) && !attrs.has(property.key))
+                            attrs.set(property.key, property.value);
+                }
+                this.attrs.set(node, attrs);
+            }
+            return attrs;
+        };
+        /*  access the specification tree exclusively, as the plain AST
+            objects would otherwise be tasted by the built-in JSON adapter  */
+        const adapter = {
+            taste: (node) => node === specification || this.parents.has(node),
+            getParentNode: (node) => this.parents.get(node) ?? null,
+            getChildNodes: (node) => "artifacts" in node ? node.artifacts :
+                "objects" in node ? node.objects : node.children,
+            getNodeType: (node) => "artifacts" in node ? "specification" :
+                "objects" in node ? "artifact" : node.kind.replace(/\s+/g, "-"),
+            getNodeAttrNames: (node) => Array.from(attributesOf(node).keys()),
+            getNodeAttrValue: (node, attr) => attributesOf(node).get(attr)
+        };
+        this.astq.adapter(adapter, true);
+        this.astq.func("refs", (_adapter, node) => "kind" in node ? referenceTargets(this.index, node) : []);
+    }
+    /*  query the nodes an ASTq selector matches, starting at the root,
+        with the values of the "{name}" parameters of the selector  */
+    query(selector, params) {
+        return this.astq.query(this.specification, selector, params);
+    }
+    /*  the parent of a node (undefined for the root)  */
+    parent(node) {
+        return this.parents.get(node);
+    }
+    /*  register a custom query function (or replace a registered one)  */
+    func(name, fn) {
+        this.astq.func(name, fn);
+        return this;
+    }
+    /*  replace the references of a Markdown text (outside its code) by
+        the names of their targets, resolved nearest to the referencing
+        object (if given), an unresolvable one keeping its reference text  */
+    expand(text, from) {
+        return expandReferences(text, (reference) => resolveUnique(this.index, reference, from).target?.name ?? reference);
+    }
+    /*  render a Markdown text (a description part or property value) into plain text  */
+    plain(text, from) {
+        return plainOf(marked.lexer(this.expand(text, from)), "\n\n");
+    }
+    /*  render a Markdown text (a description part or property value) into an HTML fragment  */
+    html(text, from) {
+        return marked.parse(this.expand(text, from), { async: false });
+    }
+}

package/dst/specbook-mcp.js

@@ -8,7 +8,7 @@ import * as path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, projectFile, omitAspects, fetchModes, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, projectFile, omitAspects, fetchModes, version, renderNodes, queryFormats, parseQueryOutput } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -143,6 +143,47 @@ export const serveMcp = async (verbose) => {
             return errorResult(err);
         }
     });
+    server.registerTool("specbook_query", {
+        title: "Query Specification",
+        description: "Load all specification Markdown files below the base directory (or, with " +
+            "\"schema\", the effective YAML schema configuration itself, described as a SpecBook document " +
+            "through the bundled meta schema configuration), strictly validated, and query its Abstract " +
+            "Syntax Tree (AST) 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 (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. 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 if an output path is given, else returned directly.",
+        inputSchema: { config, basedir, fetch, gitignore, cwd,
+            schema: z.boolean().optional().describe("query the effective YAML schema configuration " +
+                "itself as a SpecBook document instead of the specification (the base directory is not " +
+                "applicable then; default: false)"),
+            selector: z.string().describe("the ASTq selector of the nodes to return"),
+            params: z.record(z.string(), z.string()).optional().describe("the values of the \"{name}\" " +
+                "parameters of the selector (default: none)"),
+            format: z.enum(queryFormats).optional().describe("output format (default: inferred from the " +
+                "output file like for the export, else json)"),
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)")
+        }
+    }, async (args) => {
+        try {
+            const { selector, params, format, output, ...options } = args;
+            const spec = parseQueryOutput(output ?? "-", format);
+            const document = await specbook.load(options);
+            const text = renderNodes(document.query(selector, params), spec.format);
+            if (spec.output !== "-") {
+                await fs.promises.writeFile(outputOf(args, spec.output), text);
+                return { content: [{ type: "text", text: `queried specification into "${spec.output}" ` +
+                                `(${Buffer.byteLength(text)} bytes)` }] };
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
         description: "Describe the SpecBook models and formats as a Markdown document, which embeds the " +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.6.0",
+    "version":                             "1.6.1",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -39,6 +39,7 @@
         "textframe":                       "1.2.1",
         "@swc/html":                       "1.16.21",
         "tokenizr":                        "2.2.1",
+        "astq":                            "2.8.3",
         "randexp":                         "0.6.1",
         "wrap-ansi":                       "10.0.2",
         "playwright":                      "1.64.1",