@rse/ase 2.0.2 → 2.0.4

package/dst/ase-setup-settings.js

@@ -252,7 +252,6 @@ export class SetupSettings {
         /*  the OpenAI Codex CLI has no scriptable statusline mechanism at all  */
         if (tool === "codex")
             return [];
-        const home = os.homedir();
         const scopes = tool === "claude" ? ["user", "project", "local"] : ["user"];
         const entries = [];
         for (const scope of scopes) {
@@ -269,7 +268,7 @@ export class SetupSettings {
             if (member === undefined)
                 continue;
             entries.push({
-                file: file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file,
+                file: this.fileDisplay(file),
                 scope: tool === "claude" ? scope : "(n/a)",
                 status: this.statuslineIsOwned(member) ? "activated" : "foreign"
             });
@@ -336,7 +335,6 @@ export class SetupSettings {
     async outputStyleStatus(tool) {
         if (tool !== "claude")
             return [];
-        const home = os.homedir();
         const scopes = ["user", "project", "local"];
         const entries = [];
         for (const scope of scopes) {
@@ -353,7 +351,7 @@ export class SetupSettings {
             if (member === undefined)
                 continue;
             entries.push({
-                file: file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file,
+                file: this.fileDisplay(file),
                 scope,
                 status: this.outputStyleIsOwned(member) ? "selected" : "foreign"
             });
@@ -389,8 +387,7 @@ export class SetupSettings {
             /*  a match is the presence of the "ase@ase" key under
                 "enabledPlugins", regardless of its true/false value  */
             const plugins = settings?.enabledPlugins;
-            if (plugins !== undefined && plugins !== null
-                && Object.prototype.hasOwnProperty.call(plugins, "ase@ase")) {
+            if (plugins !== undefined && plugins !== null && Object.hasOwn(plugins, "ase@ase")) {
                 if (scope !== "user")
                     this.log.write("info", `setup: detected ASE plugin installation in scope "${scope}"`);
                 return scope;
@@ -488,7 +485,7 @@ export class SetupSettings {
         return files;
     }
     /*  abbreviate the home directory of a file path as "~"  */
-    telemetryFileDisplay(file) {
+    fileDisplay(file) {
         const home = os.homedir();
         return file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file;
     }
@@ -796,7 +793,7 @@ export class SetupSettings {
             const present = env !== undefined && env.type() === "object" ? this.telemetryClaudePresent(env) : [];
             if (env !== undefined && present.length > 0)
                 entries.push({
-                    file: this.telemetryFileDisplay(file),
+                    file: this.fileDisplay(file),
                     scope: "user",
                     status: this.telemetryClaudeIsOwned(env) ? "activated" : "foreign"
                 });
@@ -822,7 +819,7 @@ export class SetupSettings {
                 else if ([...block.head, ...block.tail].some((line) => foreign.test(line)))
                     status = "foreign";
                 if (status !== "")
-                    entries.push({ file: this.telemetryFileDisplay(file), scope: "(n/a)", status });
+                    entries.push({ file: this.fileDisplay(file), scope: "(n/a)", status });
             }
             if (tool === "copilot" && this.telemetryCopilotForeignEnv() !== undefined)
                 entries.push({ file: "$OTEL_EXPORTER_OTLP_ENDPOINT", scope: "(n/a)", status: "foreign" });

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;
@@ -347,10 +347,9 @@ export default class SetupCommand {
         });
         /*  parser for the non-negative integer "ase setup statusline" options  */
         const parseNonNeg = (name) => (value) => {
-            const n = Number.parseInt(value, 10);
-            if (!Number.isFinite(n) || n < 0)
+            if (!/^\d+$/.test(value))
                 throw new Error(`invalid --${name} value: "${value}" (expected a non-negative integer)`);
-            return n;
+            return Number.parseInt(value, 10);
         };
         /*  register CLI sub-command "ase setup statusline"  */
         const statuslineCmd = setupCmd

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 ?