@esneiderbravo/speclaw 0.1.14 → 0.1.15

package/dist/cli/commands/version.js

@@ -0,0 +1,31 @@
+import { pkgVersion } from "../../shared/version.js";
+import { checkForUpdates, upgradeNotice } from "../lib/update-check.js";
+/**
+ * Print the locally installed speclaw version and, when a newer version is
+ * published on npm, a clickable suggestion to upgrade.
+ *
+ * The installed version (from the package's own `package.json`) always goes to
+ * **stdout** as a bare line, so it stays script- and pipe-friendly
+ * (`v=$(speclaw --version)`). The upgrade suggestion — which requires a network
+ * lookup — goes to **stderr** and only when stderr is an interactive TTY and
+ * the notifier is not disabled, so scripts and CI pay no network cost and get
+ * clean output. The lookup is forced (bypasses the daily cache) so an explicit
+ * version query reflects npm right now, and every failure is swallowed: a
+ * flaky or offline registry must never break `--version`.
+ */
+export async function runVersion() {
+    console.log(pkgVersion());
+    if (process.env.NO_UPDATE_NOTIFIER || process.env.SPECLAW_NO_UPDATE_NOTIFIER)
+        return;
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        const { current, latest, updateAvailable } = await checkForUpdates({ force: true });
+        if (updateAvailable && latest) {
+            process.stderr.write("\n" + upgradeNotice(current, latest) + "\n\n");
+        }
+    }
+    catch {
+        /* the update check is best-effort — never let it break `--version` */
+    }
+}

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseFlags } from "./lib/args.js";
-import { ui } from "./lib/ui.js";
+import { ui, header } from "./lib/ui.js";
 import { maybeNotifyUpdate } from "./lib/update-check.js";
 const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Lawbook)
 
@@ -36,7 +36,40 @@ Other
   doctor                   Verify the installation
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
+  --version                Print the installed speclaw version
 `;
+// Commands that open with the one-line branded header. These are the
+// interactive, human-facing commands whose stdout is prose. Deliberately
+// excluded: `version`/`--version`/`-v` (bare scriptable value), the Compass
+// query family (`explore`/`search`/`recall`/`impact`/`trace`, machine-consumed
+// output), `mcp` (a long-running stdio server), and `init` (already opens with
+// the fuller `banner()`).
+const HEADER_COMMANDS = new Set([
+    undefined,
+    "help",
+    "--help",
+    "-h",
+    "update",
+    "agent",
+    "doctor",
+    "index",
+    "watch",
+    "lawbook",
+]);
+/**
+ * Print the branded header once, ahead of a command's output, when it is a
+ * header-eligible command AND stdout is an interactive terminal (so pipes,
+ * redirection, and CI stay clean — mirroring the color gate in `ui.ts`). A
+ * forced-color signal counts as interactive so the header is exercisable in a
+ * child process.
+ */
+function maybeHeader(cmd) {
+    if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
+        return;
+    if (!HEADER_COMMANDS.has(cmd))
+        return;
+    header();
+}
 /** Run the handler for a single command. Returns when the command completes. */
 async function dispatch(cmd, flags) {
     switch (cmd) {
@@ -46,6 +79,10 @@ async function dispatch(cmd, flags) {
         case "-h":
             console.log(HELP);
             return;
+        case "version":
+        case "--version":
+        case "-v":
+            return (await import("./commands/version.js")).runVersion();
         case "mcp": {
             const { startMcpServer } = await import("../server.js");
             await startMcpServer();
@@ -83,6 +120,7 @@ async function dispatch(cmd, flags) {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    maybeHeader(cmd);
     await dispatch(cmd, flags);
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/ui.js

@@ -2,6 +2,7 @@
 // = the "law", cream text, muted gray, green/amber for status) rendered as
 // 24-bit truecolor ANSI — no dependency needed. Colors auto-disable when the
 // output is not a TTY or NO_COLOR is set.
+import { pkgVersion } from "../../shared/version.js";
 const PALETTE = {
     cyan: [46, 230, 230], // #2EE6E6 — the accent / "law"
     cyanDim: [23, 193, 193], // #17C1C1
@@ -12,6 +13,44 @@ const PALETTE = {
     red: [235, 90, 90],
 };
 const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") && !process.env.NO_COLOR;
+// Whether the terminal reliably renders the unicode box/block glyphs the brand
+// output uses. Non-Windows terminals are assumed capable; a Windows console is
+// trusted only under a modern-terminal signal (Windows Terminal, an embedding
+// program like VS Code, or CI) — a legacy conhost with a non-UTF-8 code page
+// would otherwise show mojibake. No dependency; the check runs once at load.
+const unicodeOn = process.platform !== "win32" ||
+    Boolean(process.env.WT_SESSION || process.env.TERM_PROGRAM || process.env.CI);
+// The brand glyph set, resolved once against terminal capability. Every branded
+// renderer (header, banner, box, progress) draws from this so unicode and ASCII
+// terminals degrade together instead of one surface emitting unrenderable
+// glyphs. The ASCII fallbacks are chosen to preserve each drawing's shape.
+const G = unicodeOn
+    ? {
+        diamond: "◈",
+        dot: "·",
+        boxTL: "╭",
+        boxTR: "╮",
+        boxBL: "╰",
+        boxBR: "╯",
+        boxV: "│",
+        boxH: "─",
+        bar: "▇",
+        fill: "█",
+        track: "░",
+    }
+    : {
+        diamond: ">",
+        dot: "-",
+        boxTL: "+",
+        boxTR: "+",
+        boxBL: "+",
+        boxBR: "+",
+        boxV: "|",
+        boxH: "-",
+        bar: "#",
+        fill: "#",
+        track: "-",
+    };
 function paint(rgb, s) {
     if (!colorOn)
         return s;
@@ -20,6 +59,22 @@ function paint(rgb, s) {
 function bold(s) {
     return colorOn ? `\x1b[1m${s}\x1b[0m` : s;
 }
+/**
+ * Wrap `label` in an OSC 8 terminal hyperlink pointing at `url`, so a
+ * capable terminal renders it as a clickable link. Terminals that don't
+ * support OSC 8 simply ignore the escapes and show the label. Falls back to a
+ * plain `label (url)` when rich output is off (non-TTY / NO_COLOR) so piped and
+ * dumb-terminal output stays legible.
+ *
+ * @param label - The visible, clickable text.
+ * @param url - The target the terminal opens on click.
+ * @returns The label wrapped as a hyperlink, or `label (url)` when off.
+ */
+export function link(label, url) {
+    if (!colorOn)
+        return `${label} (${url})`;
+    return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
 /** Brand color helpers for composing styled strings. */
 export const c = {
     cyan: (s) => paint(PALETTE.cyan, s),
@@ -42,21 +97,43 @@ export const ui = {
     plain: (s = "") => console.log(s),
     code: (s) => c.cyan(s),
 };
+/**
+ * A single-line branded header — mark · name · installed version · tagline —
+ * printed once at the top of interactive commands (see `src/cli/index.ts`). The
+ * version comes from the cached {@link pkgVersion}. Glyphs degrade to ASCII on
+ * terminals without reliable unicode, and the styling no-ops to plain text when
+ * color is off, so the line stays legible everywhere.
+ *
+ * Example: `◈ speclaw  v0.1.15 · where specs become law`
+ */
+export function header() {
+    const mark = c.cyan(G.diamond);
+    const name = bold(c.cream("speclaw"));
+    const ver = c.muted("v" + pkgVersion());
+    const tag = c.muted(G.dot + " where specs become law");
+    console.log(`${mark} ${name}  ${ver} ${tag}`);
+}
 /**
  * The speclaw wordmark + logo mark (a document whose bottom line — the law — is
  * highlighted in cyan). Printed at the top of `speclaw init`.
  */
 export function banner() {
-    const bar = c.cyan("▇▇▇▇▇▇");
-    const line = c.muted("──────");
+    const H = G.boxH;
+    const bar = c.cyan(G.bar.repeat(6));
+    const line = c.muted(H.repeat(6));
     const edge = c.muted;
     console.log();
-    console.log("  " + edge("╭────────╮"));
-    console.log("  " + edge("│ ") + line + edge(" │") + "   " + bold(c.cream("s p e c l a w")));
-    console.log("  " + edge("│ ") + c.muted("────  ") + edge(" │") + "   " + c.muted("where specs become law"));
-    console.log("  " + edge("│ ") + c.muted("─────") + " " + edge(" │"));
-    console.log("  " + edge("│ ") + bar + edge(" │"));
-    console.log("  " + edge("╰────────╯"));
+    console.log("  " + edge(G.boxTL + H.repeat(8) + G.boxTR));
+    console.log("  " + edge(G.boxV + " ") + line + edge(" " + G.boxV) + "   " + bold(c.cream("s p e c l a w")));
+    console.log("  " +
+        edge(G.boxV + " ") +
+        c.muted(H.repeat(4) + "  ") +
+        edge(" " + G.boxV) +
+        "   " +
+        c.muted("where specs become law"));
+    console.log("  " + edge(G.boxV + " ") + c.muted(H.repeat(5)) + " " + edge(" " + G.boxV));
+    console.log("  " + edge(G.boxV + " ") + bar + edge(" " + G.boxV));
+    console.log("  " + edge(G.boxBL + H.repeat(8) + G.boxBR));
     console.log();
 }
 /** Render a single-line progress bar on stderr (so stdout stays clean). */
@@ -66,7 +143,7 @@ export function renderProgress(done, total, label) {
     const width = 26;
     const ratio = total > 0 ? done / total : 1;
     const filled = Math.round(ratio * width);
-    const bar = c.cyan("█".repeat(filled)) + c.muted("░".repeat(width - filled));
+    const bar = c.cyan(G.fill.repeat(filled)) + c.muted(G.track.repeat(width - filled));
     const pct = c.cyanDim(String(Math.round(ratio * 100)).padStart(3) + "%");
     const shortLabel = label.length > 38 ? "…" + label.slice(-37) : label;
     process.stderr.write(`\r  ${bar} ${pct}  ${c.muted(shortLabel.padEnd(38))}`);
@@ -78,11 +155,12 @@ export function clearProgress() {
 /** Draw a cyan-bordered block (used for the copy-paste agent prompt). */
 export function box(lines, title) {
     const width = Math.min(72, Math.max(...lines.map((l) => l.length), title?.length ?? 0) + 2);
+    const H = G.boxH;
     const top = title
-        ? "╭─ " + c.cyanDim(title) + " " + "─".repeat(Math.max(0, width - title.length - 3))
-        : "╭" + "─".repeat(width);
-    console.log("  " + c.muted(top) + c.muted("╮"));
+        ? G.boxTL + H + " " + c.cyanDim(title) + " " + H.repeat(Math.max(0, width - title.length - 3))
+        : G.boxTL + H.repeat(width);
+    console.log("  " + c.muted(top) + c.muted(G.boxTR));
     for (const l of lines)
-        console.log("  " + c.muted("│ ") + c.cream(l.padEnd(width - 2)) + c.muted(" │"));
-    console.log("  " + c.muted("╰" + "─".repeat(width) + "╯"));
+        console.log("  " + c.muted(G.boxV + " ") + c.cream(l.padEnd(width - 2)) + c.muted(" " + G.boxV));
+    console.log("  " + c.muted(G.boxBL + H.repeat(width) + G.boxBR));
 }

package/dist/cli/lib/update-check.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pkgName, pkgVersion } from "../../shared/version.js";
-import { c } from "./ui.js";
+import { c, link } from "./ui.js";
 // A lightweight, best-effort update notifier. The registry is queried at most
 // once a day (result cached under ~/.speclaw/), the lookup is time-boxed, and
 // every failure is swallowed — checking for updates must never slow down or
@@ -95,9 +95,36 @@ export async function checkForUpdates(opts = {}) {
     }
     return { current, latest, updateAvailable: !!latest && isNewer(latest, current) };
 }
+/** The public npm page for a package, where an upgrade can be reviewed. */
+export function npmPackageUrl(name) {
+    return `https://www.npmjs.com/package/${name}`;
+}
+/**
+ * Build the two-line "update available" notice. The latest version is rendered
+ * as a clickable link to the package's npm page, so a capable terminal lets the
+ * user open the release with a single click while `speclaw update` remains the
+ * command that performs the upgrade.
+ *
+ * @param current - The installed version.
+ * @param latest - The newest published version.
+ * @returns The formatted, styled notice (no leading/trailing blank lines).
+ */
+export function upgradeNotice(current, latest) {
+    const latestLink = c.cyan(link(latest, npmPackageUrl(pkgName())));
+    return ("  " +
+        c.amber("⬆ speclaw ") +
+        c.muted(current + " → ") +
+        latestLink +
+        c.muted(" available") +
+        "\n" +
+        "  " +
+        c.muted("run ") +
+        c.cyan("speclaw update") +
+        c.muted(" — upgrades and applies only what's new"));
+}
 /**
- * Print a one-line "update available" notice to stderr when a newer version
- * exists. No-op for the `mcp`/`update`/`help` commands, on non-TTY stderr, or
+ * Print the "update available" notice to stderr when a newer version exists.
+ * No-op for the `mcp`/`update`/`help`/`version` commands, on non-TTY stderr, or
  * when NO_UPDATE_NOTIFIER / SPECLAW_NO_UPDATE_NOTIFIER is set. Never throws.
  *
  * @param cmd - The command that just ran (used to skip noisy contexts).
@@ -110,23 +137,13 @@ export async function maybeNotifyUpdate(cmd) {
             return;
         // `init` shows its own prominent up-front warning and ends on the clean
         // copy-paste prompt — don't append a second notice after it.
-        if (!cmd || ["mcp", "update", "init", "help", "--help", "-h"].includes(cmd))
+        if (!cmd ||
+            ["mcp", "update", "init", "help", "--help", "-h", "version", "--version", "-v"].includes(cmd))
             return;
         const { current, latest, updateAvailable } = await checkForUpdates();
         if (!updateAvailable || !latest)
             return;
-        process.stderr.write("\n" +
-            "  " +
-            c.amber("⬆ speclaw ") +
-            c.muted(current + " → ") +
-            c.cyan(latest) +
-            c.muted(" available") +
-            "\n" +
-            "  " +
-            c.muted("run ") +
-            c.cyan("speclaw update") +
-            c.muted(" — upgrades and applies only what's new") +
-            "\n\n");
+        process.stderr.write("\n" + upgradeNotice(current, latest) + "\n\n");
     }
     catch {
         /* the notifier is best-effort — never let it break a command */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "publishConfig": {
     "access": "public"
   },
@@ -41,6 +41,8 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "check": "prettier --check . && eslint .",
+    "pretest": "tsc -p tsconfig.test.json && node scripts/prep-test-assets.mjs",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' 'dist-test/test/**/*.test.js'",
     "prepublishOnly": "npm run build"
   },
   "engines": {