@rse/ase 2.0.3 → 2.0.4

package/dst/ase-man.js

@@ -5,13 +5,14 @@
 */
 import path from "node:path";
 import fs from "node:fs";
-import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { writeStdout } from "./ase-lib-stdio.js";
+/*  the width of the manual pages printed as plain text  */
+const WIDTH = 80;
 /*  reusable functionality: resolve the internally shipped manual pages  */
 export class Man {
     /*  determine the directory of the manual pages; the build process
-        renders "man/*.md" into "dst/man/*.1" (see the "build-man" build
+        copies "man/*.md" into "dst/man/*.md" (see the "build-man" build
         step), right next to the compiled tool  */
     static dir() {
         return path.join(path.dirname(fileURLToPath(import.meta.url)), "man");
@@ -26,15 +27,15 @@ export class Man {
             throw new Error(`man: no manual pages found in "${Man.dir()}" (tool not completely built?)`, { cause: err });
         }
         return files
-            .filter((file) => /^ase(?:-[a-z0-9-]+)?\.\d$/.test(file))
-            .map((file) => file.replace(/\.\d$/, ""))
+            .filter((file) => /^ase(?:-[a-z0-9-]+)?\.md$/.test(file))
+            .map((file) => file.replace(/\.md$/, ""))
             .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
     }
-    /*  resolve the words of a requested manual page to the absolute path of
-        its file: the words are joined with dashes, the "ase" prefix is optional,
-        and a command path deeper than the shipped pages (e.g. "ase task store
-        start") falls back to the page of its nearest parent (e.g. "ase-task-store"),
-        as the pages of a group with third-level commands cover them  */
+    /*  resolve the words of a requested manual page to its name: the words
+        are joined with dashes, the "ase" prefix is optional, and a command path
+        deeper than the shipped pages (e.g. "ase task store start") falls back to
+        the page of its nearest parent (e.g. "ase-task-store"), as the pages of a
+        group with third-level commands cover them  */
     static resolve(words) {
         const name = words.join("-").toLowerCase();
         if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
@@ -46,7 +47,7 @@ export class Man {
         while (parts.length > 0) {
             const page = parts.join("-");
             if (pages.has(page))
-                return path.join(Man.dir(), `${page}.1`);
+                return page;
             parts.pop();
             if (parts.length === 1)
                 break;
@@ -64,33 +65,38 @@ export default class ManCommand {
     register(program) {
         program
             .command("man")
-            .description("Show an internally shipped manual page with man(1)")
+            .description("Browse all manual pages interactively, or print a manual page as plain text")
             .argument("[page...]", "manual page name, either as \"ase-<command>[-<sub-command>]\" " +
-            "or as the words of the command path (\"ase\" prefix optional, default: \"ase\")")
+            "or as the words of the command path (\"ase\" prefix optional), selected in the " +
+            "interactive browser on a terminal (or searched for, if no manual page fits exactly), " +
+            "else printed as plain text (default: \"ase\")")
             .option("-l, --list", "list the names of all shipped manual pages instead", false)
-            .option("-p, --path", "print the path of the manual page file instead", false)
             .action(async (words, opts) => {
             /*  list all manual pages  */
             if (opts.list) {
                 await writeStdout(Man.list().map((page) => `${page}\n`).join(""));
                 return;
             }
-            /*  resolve manual page  */
-            const file = Man.resolve(words.length > 0 ? words : ["ase"]);
-            if (opts.path) {
-                await writeStdout(`${file}\n`);
+            /*  browse all manual pages interactively (only on a terminal), with
+                the given manual page selected resp. searched for (if any)  */
+            if (process.stdin.isTTY && process.stdout.isTTY) {
+                const { runManTUI } = await import("./ase-man-tui.js");
+                await runManTUI(this.log, words);
                 return;
             }
-            /*  show manual page with man(1), passing the file by its path,
-                which all common man(1) implementations support  */
-            this.log.write("debug", `man: showing manual page "${file}"`);
-            const result = spawnSync("man", [file], { stdio: "inherit" });
-            if (result.error !== undefined) {
-                const message = result.error.message;
-                throw new Error(`man: failed to run man(1): ${message} ` +
-                    `(the manual page file is "${file}")`, { cause: result.error });
-            }
-            process.exitCode = result.status ?? 1;
+            /*  resolve manual page, where a skill or command fitting exactly
+                is preferred over the fallback onto the nearest parent command  */
+            const { loadCatalog, findPage } = await import("./ase-man-catalog.js");
+            const { renderPage } = await import("./ase-man-render.js");
+            const catalog = loadCatalog();
+            const request = words.length > 0 ? words : ["ase"];
+            const page = findPage(catalog, request) ?? catalog.pages.get(`${Man.resolve(request)}.1`);
+            if (page === undefined)
+                throw new Error(`man: no manual page found for "${request.join(" ")}" (see "ase man --list")`);
+            /*  print manual page as plain text  */
+            this.log.write("debug", `man: printing manual page "${page.id}"`);
+            const { lines } = renderPage(page.md, WIDTH, page.id, (id) => catalog.pages.has(id));
+            await writeStdout(lines.map((line) => line.map((span) => span.text).join("").trimEnd() + "\n").join(""));
         });
     }
 }

package/dst/ase-setup.js

@@ -71,10 +71,10 @@ export default class SetupCommand {
             await this.runner.run(spec.cli, ["plugin", spec.pInstall, "ase@ase", ...scopeArgs], { retries: 3 });
         }
         else {
-            /*  perform NPM version check  */
+            /*  perform direct NPM registry version check  */
             const current = Version.current();
             this.log.write("info", `setup: update: used ASE version: ${current}`);
-            const latest = await Version.latest();
+            const latest = await Version.latest(true);
             if (!force && latest !== "" && latest === current) {
                 this.log.write("info", `setup: update: ASE already at latest version ${current}`);
                 return 0;

package/dst/ase-spec.js

@@ -5,6 +5,7 @@
 */
 import path from "node:path";
 import fs from "node:fs";
+import os from "node:os";
 import { isScalar } from "yaml";
 import { z } from "zod";
 import sourceCodeError from "source-code-error";
@@ -14,11 +15,11 @@ import { Config } from "./ase-config-core.js";
 import { configSchema } from "./ase-config-schema.js";
 import { Task } from "./ase-task.js";
 import { Artifact } from "./ase-artifact.js";
-import { Meta } from "./ase-util-meta.js";
 import { writeStdout } from "./ase-lib-stdio.js";
-/*  reusable functionality: lint, export, and preview the SpecBook-based
-    project specification, located via the "project.artifact.spec.basedir"
-    and "project.artifact.spec.schema" configuration  */
+/*  reusable functionality: initialize, lint, export, 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
         against SpecBook at compile-time) to not load SpecBook for the MCP schema  */
@@ -28,8 +29,9 @@ export class Spec {
     /*  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
-        bundled standard "ase-format-specbook.yaml" plugin meta file or a file
-        path relative to the project root, and an unset or empty value means "std"  */
+        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"  */
     static configFiles(log) {
         const cfg = new Config("config", configSchema, log);
         cfg.read();
@@ -39,7 +41,7 @@ export class Spec {
         if (entries.length === 0)
             entries.push("std");
         return entries.map((entry) => entry === "std" ?
-            Meta.resolve("ase-format-specbook.yaml") :
+            "std" :
             path.resolve(Task.projectRoot(), entry));
     }
     /*  the ASE log level each SpecBook verbosity level maps onto: the
@@ -93,21 +95,81 @@ export class Spec {
             return file;
         return rel.replace(/\\/g, "/");
     }
-    /*  every specification command honors the Git exclude rules, so that
+    /*  every reading specification command honors the Git exclude rules, so that
         SpecBook resolves the very same artifact files as "ase artifact
         list --kind spec": both consult ".gitignore", so a specification
         the project does not track is invisible to both instead of only
         to one of them  */
     static gitignore = true;
+    /*  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) {
+        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
+            })));
+            return result.files.map((file) => Spec.relativize(path.join(basedir, file)));
+        }
+        finally {
+            await fs.promises.rm(cwd, { recursive: true, force: true });
+        }
+    }
     /*  lint the specification Markdown files below the "spec" artifact
-        base directory against the schema configuration  */
-    static async lint(log) {
+        base directory against the schema configuration, optionally
+        followed by the generic Markdown linting  */
+    static async lint(log, markdown = false) {
         const result = await Spec.unmarked(Spec.api(log).then((api) => api.lint({
             config: Spec.configFiles(log),
             basedir: Artifact.basedir(log, "spec"),
             gitignore: Spec.gitignore
         })));
-        return result.diagnostics.map((d) => ({ ...d, file: Spec.relativize(d.file) }));
+        const diagnostics = result.diagnostics.map((d) => ({ ...d, file: Spec.relativize(d.file) }));
+        return markdown ? diagnostics.concat(await Spec.markdownlint(log)) : diagnostics;
+    }
+    /*  the markdownlint rules conflicting with the SpecBook format
+        (trailing blank line, mixed ATX and Setext headings, free ordered list numbering,
+        padded list markers and headings, unwrapped lines, frontmatter first, images without
+        alternate text, and multiple artifacts or same-named objects per file)  */
+    static markdownConfig = {
+        "no-multiple-blanks": { maximum: 2 },
+        "heading-style": false,
+        "ol-prefix": false,
+        "no-alt-text": false,
+        "list-marker-space": false,
+        "ul-indent": false,
+        "no-multiple-space-atx": false,
+        "line-length": false,
+        "first-line-heading": false,
+        "single-title": false,
+        "no-duplicate-heading": false,
+        "no-inline-html": false
+    };
+    /*  the message prefix of the markdownlint diagnostics  */
+    static markdownPrefix = "markdownlint: ";
+    /*  lint the specification Markdown files with markdownlint, reporting
+        its findings as warnings, as they never break the SpecBook parsing
+        (markdownlint itself is loaded on first use only)  */
+    static async markdownlint(log) {
+        const { lint } = await import("markdownlint/promise");
+        const files = Artifact.list(log, ["spec"]).flatMap((entry) => entry.files)
+            .filter((file) => /\.md$/i.test(file))
+            .map((file) => path.resolve(Task.projectRoot(), file));
+        const results = await lint({ files, config: Spec.markdownConfig });
+        return Object.entries(results).flatMap(([file, errors]) => errors.map((e) => ({
+            file: Spec.relativize(file),
+            line: e.lineNumber,
+            column: e.errorRange?.[0] ?? 1,
+            severity: "warning",
+            message: `${Spec.markdownPrefix}${e.ruleNames.join("/")}: ${e.ruleDescription}` +
+                (e.errorDetail !== null ? ` [${e.errorDetail}]` : "") +
+                (e.errorContext !== null ? ` [context: "${e.errorContext}"]` : "")
+        })));
     }
     /*  render a diagnostic as a multi-line message with the affected
         source snippet (like the verbose SpecBook CLI), falling back to
@@ -182,22 +244,39 @@ export default class SpecCommand {
         /*  register CLI top-level command "ase spec"  */
         const spec = program
             .command("spec")
-            .description("Lint, export, and preview the SpecBook-based project specification")
+            .description("Initialize, lint, export, and preview the SpecBook-based project specification")
             .action(() => {
             spec.outputHelp();
             process.exit(1);
         });
+        /*  register CLI sub-command "ase spec init"  */
+        spec
+            .command("init")
+            .description("Initialize the absent specification Markdown files of the SpecBook schema configuration")
+            .action(async () => {
+            const files = await Spec.init(this.log);
+            await writeStdout(files.length > 0 ?
+                `initialized artifact file(s): ${files.join(", ")}\n` :
+                "no artifact files were created\n");
+        });
         /*  register CLI sub-command "ase spec lint"  */
         spec
             .command("lint")
             .description("Lint the specification Markdown files against the SpecBook schema configuration")
+            .option("-m, --markdown", "additionally lint the generic Markdown formatting via markdownlint")
             .option("-v, --verbose", "print each diagnostic with its affected source snippet")
             .action(async (opts) => {
-            const diagnostics = await Spec.lint(this.log);
-            for (const diagnostic of diagnostics)
-                await writeStdout(opts.verbose === true ?
-                    Spec.render(diagnostic, process.stdout.isTTY === true) :
-                    `${renderDiagnostic(diagnostic)}\n`);
+            const diagnostics = await Spec.lint(this.log, opts.markdown === true);
+            for (const diagnostic of diagnostics) {
+                /*  report a diagnostic as a log message of its severity, tagged with its linter  */
+                const { file, line, column, severity, message } = diagnostic;
+                const markdown = message.startsWith(Spec.markdownPrefix);
+                if (opts.verbose === true)
+                    await writeStdout(Spec.render(diagnostic, process.stdout.isTTY === true));
+                else
+                    this.log.write(severity, `lint: ${markdown ? "markdownlint" : "specbook"}: ` +
+                        `${file}:${line}:${column}: ${markdown ? message.slice(Spec.markdownPrefix.length) : message}`);
+            }
             if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
                 process.exitCode = 1;
         });
@@ -272,8 +351,10 @@ export class SpecMCP {
             description: "Lint the SpecBook specification Markdown files of the project (located via the " +
                 "`project.artifact.spec.basedir` configuration) against the SpecBook YAML schema " +
                 "configuration (`project.artifact.spec.schema`, a whitespace-separated list of schema files " +
-                "merged in order, with `std` naming the bundled standard `ase-format-specbook.yaml`, " +
-                "which is also the default). " +
+                "merged in order, with `std` naming the standard schema bundled with SpecBook, " +
+                "which is also the default). With `markdown`, the files are additionally linted " +
+                "for their generic Markdown formatting via markdownlint, whose findings are reported " +
+                "as `warning` diagnostics with a message prefixed by `markdownlint: `. " +
                 "Returns a `diagnostics` array of `{ file, line, column, severity, message }` objects (with " +
                 "project-relative `file` and a `severity` of `error` or `warning`), rendered as bullet " +
                 "points in `text`. With `verbose`, " +
@@ -282,6 +363,8 @@ export class SpecMCP {
                 "(`text` of `specification valid`) means the specification is valid; only " +
                 "diagnostics of `error` severity make an export fail.",
             inputSchema: {
+                markdown: z.boolean().optional()
+                    .describe("if true, additionally lint the generic Markdown formatting via markdownlint (default: false)"),
                 verbose: z.boolean().optional()
                     .describe("if true, render each diagnostic with its affected source snippet (default: false)")
             },
@@ -299,7 +382,7 @@ export class SpecMCP {
         }, async (args) => {
             try {
                 const verbose = args.verbose ?? false;
-                const diagnostics = (await Spec.lint(this.log))
+                const diagnostics = (await Spec.lint(this.log, args.markdown ?? false))
                     .map((d) => verbose ? { ...d, snippet: Spec.render(d, false) } : d);
                 const text = diagnostics.length === 0 ? "specification valid" :
                     verbose ?

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

@@ -5,10 +5,11 @@
 */
 import { effortSizes } from "./ase-task-format.js";
 /*  shortest keyword still eligible for fuzzy matching: below it the
-    edit distance would equate it with almost any short word  */
-const fuzzyMin = 4;
+    edit distance would equate it with almost any short word
+    (shared with the search of the manual page browser)  */
+export const fuzzyMin = 4;
 /*  the Levenshtein edit distance of two words  */
-const levenshtein = (a, b) => {
+export const levenshtein = (a, b) => {
     let prev = [];
     let curr = [];
     for (let j = 0; j <= b.length; j++)
@@ -24,7 +25,7 @@ const levenshtein = (a, b) => {
     return prev[b.length];
 };
 /*  the Sorensen-Dice bigram similarity coefficient of two words  */
-const diceCoefficient = (a, b) => {
+export const diceCoefficient = (a, b) => {
     if (a === b)
         return 1;
     if (a.length < 2 || b.length < 2)