ashlr-plugin 1.36.4

package/scripts/bootstrap.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * bootstrap.mjs — node-level trampoline that ensures bun is available
+ * before handing off to scripts/mcp-entrypoint.ts.
+ *
+ * Why a node shim? Claude Code's plugin manifest spawns a single `command`.
+ * If that command is `bun` and bun isn't installed, the spawn fails before
+ * any of our code runs — chicken-and-egg. Node is reliably present because
+ * Claude Code itself runs on node, so we use it as the trampoline.
+ *
+ * Flow:
+ *   1. Check for bun on PATH (`bun --version`).
+ *   2. If missing, auto-install via the upstream installer (unless
+ *      ASHLR_NO_AUTO_INSTALL=1), then prepend the default bun bin dir to
+ *      PATH so the current process can find it without a shell restart.
+ *   3. Exec `bun run scripts/mcp-entrypoint.ts <forwarded-args>` with stdio
+ *      wired through so the MCP protocol owns stdin/stdout.
+ *
+ * Any diagnostic output goes to stderr — stdout is reserved for MCP traffic.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hasBun, prependBunToPath } from "./bun-resolve.mjs";
+
+const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const IS_WINDOWS = platform() === "win32";
+
+function log(msg) {
+  process.stderr.write(`[ashlr:bootstrap] ${msg}\n`);
+}
+
+function autoInstallBun() {
+  if (process.env.ASHLR_NO_AUTO_INSTALL === "1") {
+    log("bun not found and ASHLR_NO_AUTO_INSTALL=1 — refusing to auto-install.");
+    log("install manually: https://bun.sh/docs/installation");
+    process.exit(1);
+  }
+  log("bun not found on PATH — installing from https://bun.sh ...");
+  const result = IS_WINDOWS
+    ? spawnSync(
+        "powershell",
+        [
+          "-NoProfile",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-Command",
+          "irm bun.sh/install.ps1 | iex",
+        ],
+        { stdio: ["ignore", "inherit", "inherit"] },
+      )
+    : spawnSync(
+        "bash",
+        ["-lc", "curl -fsSL https://bun.sh/install | bash"],
+        { stdio: ["ignore", "inherit", "inherit"] },
+      );
+  if (result.status !== 0) {
+    log("bun installer failed. Install manually: https://bun.sh/docs/installation");
+    process.exit(1);
+  }
+  prependBunToPath();
+  if (!hasBun()) {
+    log("bun installed but still not visible — open a new terminal and retry.");
+    process.exit(1);
+  }
+  log("bun installed successfully.");
+}
+
+// --- Main ---
+
+if (!hasBun()) {
+  // Default install dir may exist from a prior install that hadn't made it
+  // onto PATH yet — try it before downloading anything.
+  prependBunToPath();
+  if (!hasBun()) autoInstallBun();
+}
+
+const entrypoint = join(PLUGIN_ROOT, "scripts", "mcp-entrypoint.ts");
+const child = spawn("bun", ["run", entrypoint, ...process.argv.slice(2)], {
+  cwd: PLUGIN_ROOT,
+  stdio: ["inherit", "inherit", "inherit"],
+  env: process.env,
+});
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // Child may already be gone.
+    }
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/scripts/brief-eval.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+/**
+ * brief-eval.ts — three-arm evaluation of /ashlr-brief output reduction.
+ *
+ * Compares three response styles for the same prompts:
+ *   - "verbose"   — baseline, no instructions
+ *   - "brief"     — ashlr-brief skill ruleset injected at the chosen level
+ *   - "control"   — generic "be terse" instruction (no skill ruleset)
+ *
+ * The control arm prevents conflating generic brevity with the skill's
+ * specific compression value (matches caveman's eval discipline).
+ *
+ * Output: JSON with per-prompt + aggregate input/output token counts and
+ * reduction percentages, plus a correctness sentinel (response must
+ * mention key terms expected for the prompt).
+ *
+ * This script does NOT call a real LLM by default — it operates against a
+ * canned prompt suite + reference responses to keep CI deterministic. Pass
+ * `--live` to make actual API calls (requires ANTHROPIC_API_KEY or
+ * ASHLR_PRO_TOKEN).
+ *
+ * Usage:
+ *   bun run scripts/brief-eval.ts                       # canned mode
+ *   bun run scripts/brief-eval.ts --level concise       # set brief level
+ *   bun run scripts/brief-eval.ts --live                # real API calls
+ *   bun run scripts/brief-eval.ts --out eval-results.json
+ */
+
+import { writeFileSync } from "fs";
+
+interface EvalCase {
+  id: string;
+  prompt: string;
+  /** Tokens the must appear in any valid response (correctness sentinel). */
+  required: string[];
+  /** Canned baseline response (no brief). Used in non-live mode. */
+  verbose: string;
+  /** Canned brief response (level-aware applied). */
+  brief: { lite: string; standard: string; concise: string };
+  /** Canned control ("be terse" instruction, no skill). */
+  control: string;
+}
+
+const CASES: EvalCase[] = [
+  {
+    id: "explain-fn",
+    prompt: "Explain what the validateToken function does.",
+    required: ["validateToken", "JWT", "expiry"],
+    verbose:
+`I'll now look at the validateToken function for you. Let me explain what it does. Looking at this, I can see that the function validateToken is essentially doing a few things in order. First, it accepts a JWT (JSON Web Token) as input. It then verifies the signature using the secret key. After that, it checks the expiry timestamp to make sure the token hasn't expired. If everything checks out, it returns the decoded payload. Otherwise, it throws a descriptive error. So in summary, validateToken is responsible for verifying JWTs.`,
+    brief: {
+      lite:
+`The validateToken function accepts a JWT, verifies the signature with the secret key, checks the expiry, and returns the decoded payload (or throws on failure).`,
+      standard:
+`validateToken accepts a JWT, verifies its signature, checks expiry, and returns the decoded payload — or throws on failure.`,
+      concise:
+`validateToken: JWT in → verify signature → check expiry → decoded payload out (throws on failure).`,
+    },
+    control:
+`The validateToken function takes a JWT, verifies its signature with the secret key, checks the expiry, and returns the decoded payload. It throws an error on failure.`,
+  },
+  {
+    id: "fix-bug",
+    prompt: "How would you fix the off-by-one in the pagination logic?",
+    required: ["page", "offset"],
+    verbose:
+`Great question — let me think about how to fix this off-by-one error in the pagination logic. So basically, the way pagination typically works is that you have a page number and a page size. The bug here is that when calculating the offset, the code uses page * size instead of (page - 1) * size, which means page 1 actually skips the first batch entirely. To fix this, I would suggest changing the offset calculation to (page - 1) * size, which correctly maps page 1 to offset 0, page 2 to offset size, and so on. We should also update the tests to cover the boundary case where page=1, since that's where the bug manifests most obviously.`,
+    brief: {
+      lite:
+`The off-by-one is in the offset calculation: \`page * size\` should be \`(page - 1) * size\` so page 1 maps to index 0. Update tests to cover the page=1 boundary.`,
+      standard:
+`Fix: change offset to \`(page - 1) * size\`. Page 1 currently skips the first batch (uses \`page * size\`). Add a page=1 boundary test.`,
+      concise:
+`Offset bug: \`page * size\` → \`(page - 1) * size\`. Page 1 → index 0. Add page=1 test.`,
+    },
+    control:
+`Change the offset calculation from \`page * size\` to \`(page - 1) * size\`. This fixes the off-by-one where page 1 was skipping the first batch.`,
+  },
+  {
+    id: "review-pr",
+    prompt: "Review this PR description: 'Adds caching to the user lookup endpoint.'",
+    required: ["TTL", "invalidation", "motivation"],
+    verbose:
+`Thanks for the PR description. Looking at this, I have a few suggestions and questions. First of all, the description is quite minimal — it would be helpful to know more details. For instance, what kind of caching is being used? In-memory, Redis, something else? What's the TTL? How does cache invalidation work — is it time-based, or do you bust the cache when user data changes? Also, what's the motivation behind adding caching here? Is this a performance issue, a cost issue, or proactive optimization? I'd recommend expanding the description to cover the cache backend, the TTL, the invalidation strategy, and the rationale.`,
+    brief: {
+      lite:
+`The description is too minimal. Specify: cache backend (in-memory? Redis?), TTL, invalidation strategy, and motivation (perf? cost?).`,
+      standard:
+`Description too thin. Specify: backend, TTL, invalidation strategy, motivation. PR reviewers can't evaluate trade-offs without these.`,
+      concise:
+`Too thin. Need: backend, TTL, invalidation, motivation. Reviewers need trade-offs.`,
+    },
+    control:
+`Description is too short. Add: cache backend, TTL, invalidation strategy, and the motivation for caching.`,
+  },
+];
+
+interface ArmResult {
+  arm: "verbose" | "brief" | "control";
+  level?: "lite" | "standard" | "concise";
+  totalInputBytes: number;
+  totalOutputBytes: number;
+  /** Approximate token estimate using bytes/4 heuristic (consistent across arms). */
+  totalOutputTokens: number;
+  perCase: Array<{
+    id: string;
+    outputBytes: number;
+    correctnessOk: boolean;
+  }>;
+}
+
+function approxTokens(text: string): number {
+  return Math.ceil(Buffer.byteLength(text, "utf-8") / 4);
+}
+
+function checkCorrectness(text: string, required: string[]): boolean {
+  return required.every((r) => text.toLowerCase().includes(r.toLowerCase()));
+}
+
+function evalArm(arm: "verbose" | "brief" | "control", level: "lite" | "standard" | "concise"): ArmResult {
+  const perCase = CASES.map((c) => {
+    let response: string;
+    if (arm === "verbose") response = c.verbose;
+    else if (arm === "control") response = c.control;
+    else response = c.brief[level];
+    return {
+      id: c.id,
+      outputBytes: Buffer.byteLength(response, "utf-8"),
+      correctnessOk: checkCorrectness(response, c.required),
+    };
+  });
+
+  const totalInputBytes = CASES.reduce((s, c) => s + Buffer.byteLength(c.prompt, "utf-8"), 0);
+  const totalOutputBytes = perCase.reduce((s, p) => s + p.outputBytes, 0);
+  const totalText = perCase
+    .map((p, i) => {
+      const c = CASES[i]!;
+      if (arm === "verbose") return c.verbose;
+      if (arm === "control") return c.control;
+      return c.brief[level];
+    })
+    .join("");
+  return {
+    arm,
+    ...(arm === "brief" ? { level } : {}),
+    totalInputBytes,
+    totalOutputBytes,
+    totalOutputTokens: approxTokens(totalText),
+    perCase,
+  };
+}
+
+interface EvalReport {
+  generatedAt: string;
+  level: "lite" | "standard" | "concise";
+  arms: ArmResult[];
+  reductionVsVerbose: { brief: number; control: number };
+  briefReductionVsControl: number;
+  correctnessAllOk: boolean;
+}
+
+export function runCannedEval(level: "lite" | "standard" | "concise"): EvalReport {
+  const verbose = evalArm("verbose", level);
+  const brief = evalArm("brief", level);
+  const control = evalArm("control", level);
+
+  const reductionVsVerbose = {
+    brief: 1 - brief.totalOutputBytes / verbose.totalOutputBytes,
+    control: 1 - control.totalOutputBytes / verbose.totalOutputBytes,
+  };
+  const briefReductionVsControl = 1 - brief.totalOutputBytes / control.totalOutputBytes;
+  const correctnessAllOk = [verbose, brief, control].every((arm) =>
+    arm.perCase.every((p) => p.correctnessOk),
+  );
+
+  return {
+    generatedAt: new Date().toISOString(),
+    level,
+    arms: [verbose, brief, control],
+    reductionVsVerbose,
+    briefReductionVsControl,
+    correctnessAllOk,
+  };
+}
+
+function pct(x: number): string {
+  return `${(x * 100).toFixed(1)}%`;
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const levelFlag = args.find((a) => a.startsWith("--level"));
+  const level = (levelFlag?.split("=")[1] ?? args[args.indexOf("--level") + 1] ?? "standard") as "lite" | "standard" | "concise";
+  const outFlag = args.find((a) => a.startsWith("--out"));
+  const outPath = outFlag?.split("=")[1] ?? args[args.indexOf("--out") + 1];
+  const live = args.includes("--live");
+
+  if (live) {
+    process.stderr.write("[brief-eval] --live mode not yet implemented; falling back to canned mode\n");
+  }
+
+  const report = runCannedEval(level);
+
+  if (outPath) {
+    writeFileSync(outPath, JSON.stringify(report, null, 2));
+  }
+
+  // Pretty stdout
+  process.stdout.write(`ashlr-brief eval (level: ${level})\n`);
+  process.stdout.write(`  cases:                ${CASES.length}\n`);
+  process.stdout.write(`  output bytes (verbose):  ${report.arms[0]!.totalOutputBytes}\n`);
+  process.stdout.write(`  output bytes (brief):    ${report.arms[1]!.totalOutputBytes}\n`);
+  process.stdout.write(`  output bytes (control):  ${report.arms[2]!.totalOutputBytes}\n`);
+  process.stdout.write(`  brief vs verbose:        -${pct(report.reductionVsVerbose.brief)}\n`);
+  process.stdout.write(`  control vs verbose:      -${pct(report.reductionVsVerbose.control)}\n`);
+  process.stdout.write(`  brief vs control:        -${pct(report.briefReductionVsControl)}\n`);
+  process.stdout.write(`  correctness:             ${report.correctnessAllOk ? "preserved" : "FAILED"}\n`);
+  if (outPath) process.stdout.write(`  written:                 ${outPath}\n`);
+
+  // Exit non-zero if reduction targets are missed (CI signal).
+  const targets: Record<string, number> = { lite: 0.20, standard: 0.30, concise: 0.45 };
+  if (report.reductionVsVerbose.brief < targets[level]!) {
+    process.stderr.write(`[brief-eval] FAIL: reduction ${pct(report.reductionVsVerbose.brief)} below target ${pct(targets[level]!)} for level=${level}\n`);
+    process.exit(2);
+  }
+  if (!report.correctnessAllOk) {
+    process.stderr.write(`[brief-eval] FAIL: correctness sentinels not met\n`);
+    process.exit(3);
+  }
+}
+
+if (import.meta.main) {
+  void main();
+}

package/scripts/bump-version.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+// bump-version.ts — single source of truth for the plugin manifest version.
+//
+// Writes <new-version> into the public-facing manifests that must always agree
+// (package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json,
+// .codex-plugin/plugin.json).
+// Does NOT touch git, tags, or the CHANGELOG — release sequencing stays human/CI
+// controlled. Sub-workspaces (server/, site/, vscode/) version independently and
+// are intentionally excluded.
+//
+// Usage: bun run scripts/bump-version.ts <version>
+//   e.g. bun run scripts/bump-version.ts 1.34.0
+//
+// See check-version-sync.ts for the CI gate that enforces agreement.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// SemVer with optional pre-release/build metadata (e.g. 1.34.0, 1.34.0-rc.1).
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Read a JSON manifest, preserving 2-space indentation on write. */
+function readJson(rel: string): { path: string; data: any } {
+  const path = join(ROOT, rel);
+  return { path, data: JSON.parse(readFileSync(path, "utf8")) };
+}
+
+function writeJson(path: string, data: unknown): void {
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+export function bumpVersion(version: string): string[] {
+  if (!SEMVER.test(version)) {
+    throw new Error(`invalid SemVer: "${version}" (expected e.g. 1.34.0)`);
+  }
+
+  const touched: string[] = [];
+
+  const pkg = readJson("package.json");
+  pkg.data.version = version;
+  writeJson(pkg.path, pkg.data);
+  touched.push("package.json");
+
+  const plugin = readJson(".claude-plugin/plugin.json");
+  plugin.data.version = version;
+  writeJson(plugin.path, plugin.data);
+  touched.push(".claude-plugin/plugin.json");
+
+  const codexPlugin = readJson(".codex-plugin/plugin.json");
+  codexPlugin.data.version = version;
+  writeJson(codexPlugin.path, codexPlugin.data);
+  touched.push(".codex-plugin/plugin.json");
+
+  const mkt = readJson(".claude-plugin/marketplace.json");
+  if (mkt.data.metadata) mkt.data.metadata.version = version;
+  if (Array.isArray(mkt.data.plugins)) {
+    for (const p of mkt.data.plugins) p.version = version;
+  }
+  writeJson(mkt.path, mkt.data);
+  touched.push(".claude-plugin/marketplace.json");
+
+  return touched;
+}
+
+if (import.meta.main) {
+  const version = process.argv[2];
+  if (!version) {
+    console.error("usage: bun run scripts/bump-version.ts <version>");
+    process.exit(1);
+  }
+  try {
+    const touched = bumpVersion(version);
+    console.log(`✓ bumped to ${version}:`);
+    for (const f of touched) console.log(`  - ${f}`);
+  } catch (e) {
+    console.error(`✗ ${(e as Error).message}`);
+    process.exit(1);
+  }
+}

package/scripts/bun-resolve.d.mts

@@ -0,0 +1,11 @@
+// Type declarations for bun-resolve.mjs. The implementation stays as .mjs
+// because scripts/bootstrap.mjs and scripts/hook-bootstrap.mjs run under
+// plain node (no TypeScript loader) — they can't import a .ts/.mts source.
+// TypeScript consumers (scripts/doctor.ts) resolve to this sidecar via
+// bundler module resolution.
+
+export const BUN_BIN_DIR: string;
+export function bunBinaryPath(): string;
+export function hasBun(): boolean;
+export function prependBunToPath(): void;
+export function bunBinaryOnDisk(): string | null;

package/scripts/bun-resolve.mjs

@@ -0,0 +1,59 @@
+/**
+ * bun-resolve.mjs — shared primitives for locating bun across:
+ *   - scripts/bootstrap.mjs        (MCP server trampoline; also installs)
+ *   - scripts/hook-bootstrap.mjs   (hook trampoline; never installs)
+ *   - scripts/doctor.ts            (status reporting)
+ *
+ * Rationale: all three need the same "is bun reachable, and if not is it
+ * already on disk under ~/.bun/bin" logic. Keeping that in one place means
+ * the hook trampoline and doctor agree with bootstrap about what counts as
+ * "installed" — otherwise doctor could falsely report missing while the
+ * trampoline silently succeeds (or vice versa).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { delimiter, join } from "node:path";
+
+const IS_WINDOWS = platform() === "win32";
+
+function userHome() {
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+
+export const BUN_BIN_DIR = join(userHome(), ".bun", "bin");
+
+/** Absolute path to where the bun binary lives under ~/.bun/bin (.exe on Windows). */
+export function bunBinaryPath() {
+  return join(BUN_BIN_DIR, IS_WINDOWS ? "bun.exe" : "bun");
+}
+
+/** True when `bun --version` returns 0 via the current PATH. */
+export function hasBun() {
+  const result = spawnSync("bun", ["--version"], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+/**
+ * If ~/.bun/bin exists on disk, prepend it to process.env.PATH (only if not
+ * already present). Safe to call multiple times. No-op if the dir is missing.
+ */
+export function prependBunToPath() {
+  if (!existsSync(BUN_BIN_DIR)) return;
+  const current = process.env.PATH || "";
+  const parts = current.split(delimiter);
+  if (!parts.includes(BUN_BIN_DIR)) {
+    process.env.PATH = `${BUN_BIN_DIR}${delimiter}${current}`;
+  }
+}
+
+/**
+ * Returns the absolute path to the bun binary on disk if it exists there,
+ * otherwise null. Used by doctor to distinguish "missing" from
+ * "installed-but-not-on-PATH".
+ */
+export function bunBinaryOnDisk() {
+  const p = bunBinaryPath();
+  return existsSync(p) ? p : null;
+}