ashlr-plugin 1.36.4

package/scripts/print-legend.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+/**
+ * print-legend.ts
+ *
+ * Emits a plain-text ASCII legend for every element in the ashlr status line.
+ * Invoked by the /ashlr-legend skill. No I/O dependencies beyond stdout.
+ *
+ * Output is designed for a monospace terminal, <=60 visible chars per line
+ * for the structured rows (the description wraps with a hanging indent).
+ * Box-drawing characters (U+256x) are used for the header/footer frame;
+ * they render as plain hyphens in terminals that strip Unicode.
+ */
+
+const LEGEND = `\u256d\u2500\u2500\u2500\u2500 ashlr status-line legend \u2500\u2500\u2500\u2500\u256e
+
+  ashlr  \u00b7  brand label + activity dot.
+             Dim when idle; pulses during a saving event.
+
+  \u00b7        \u2014  separator glyph between segments (middle dot).
+
+  \u2840\u2844\u2847\u28FF  \u2014  heartbeat glyph between "ashlr" and the sparkline.
+             Braille wave when active (last 4s); dim dot
+             when idle.
+
+  7d \u2581\u2582\u2583\u2585\u2587\u2588\u2587  \u2014  7-day sparkline. Each cell = one day of savings,
+             tallest cell = busiest day (scaled to full
+             block). "7d" label shown when terminal >100
+             cols; dropped on narrow windows.
+
+  ctx:NN%  \u2014  context-window pressure (how full your Claude
+             Code context is). Color tiers:
+               green  0-60%   \u2022  yellow 60-80%
+               orange 80-95%  \u2022  red+bold 95%+
+
+  session +N  \u2014  tokens saved in THIS terminal since the
+               session started.
+
+  lifetime +M  \u2014  tokens saved across every session, ever.
+
+  tip:\u2026     \u2014  rotating daily hint (one tip per day, cycles
+             through the built-in tip list). Toggle off:
+               /ashlr-settings set statusLineTips false
+
+\u2570\u2500 run /ashlr-savings for totals \u00b7 /ashlr-tour to see it in action \u2500\u256f`;
+
+if (import.meta.main) {
+  process.stdout.write(LEGEND + "\n");
+}
+
+export { LEGEND };

package/scripts/product-metadata.ts

@@ -0,0 +1,38 @@
+import { readdir } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+import { listTools } from "../servers/_tool-base";
+import "../servers/_router-handlers";
+
+export interface PublicProductCounts {
+  mcpTools: number;
+  slashCommands: number;
+}
+
+export const PUBLIC_PRODUCT_COUNTS = {
+  mcpTools: 40,
+  slashCommands: 34,
+} as const satisfies PublicProductCounts;
+
+export const PUBLIC_PRODUCT_TELEMETRY = "off by default; explicit opt-in only";
+
+export function repoRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function registeredMcpToolCount(): number {
+  return new Set(listTools().map((tool) => tool.name)).size;
+}
+
+export async function slashCommandCount(root = repoRoot()): Promise<number> {
+  const entries = await readdir(join(root, "commands"));
+  return entries.filter((name) => /^ashlr-.+\.md$/.test(name)).length;
+}
+
+export async function publicProductCounts(root = repoRoot()): Promise<PublicProductCounts> {
+  return {
+    mcpTools: registeredMcpToolCount(),
+    slashCommands: await slashCommandCount(root),
+  };
+}

package/scripts/prune-old-memories.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env bun
+/**
+ * prune-old-memories.ts — surface auto-memory entries (under
+ * `<claude-projects-dir>/memory/`) that are stale candidates for deletion.
+ *
+ * Read-only by default — prints a candidate report and exits 0. Pass
+ * `--apply` to actually delete the flagged files.
+ *
+ * Heuristics for "candidate":
+ *   1. File has not been modified in > N days (default: 30; --days=N to override)
+ *   2. There is a NEWER entry whose name starts with the same project_v<major>
+ *      prefix (e.g. project_v1.13_*.md is superseded by project_v1.14_*.md)
+ *   3. Or the entry's title contains an explicit "(superseded ...)" marker
+ *
+ * Usage:
+ *   bun run scripts/prune-old-memories.ts                       # report only
+ *   bun run scripts/prune-old-memories.ts --days=60             # 60-day cutoff
+ *   bun run scripts/prune-old-memories.ts --dir=/path/to/memory # explicit dir
+ *   bun run scripts/prune-old-memories.ts --apply               # actually delete
+ *
+ * Files removed are also removed from MEMORY.md if a single-line link to them
+ * is found (`- [.*](filename.md) — ...`).
+ *
+ * This is a hygiene tool — never run automatically. Operator-driven.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, join } from "path";
+
+interface PruneCandidate {
+  path: string;
+  name: string;
+  ageDays: number;
+  reason: string;
+}
+
+function parseArgs(argv: string[]): { dir?: string; days: number; apply: boolean } {
+  const out = { days: 30, apply: false } as { dir?: string; days: number; apply: boolean };
+  for (const a of argv) {
+    if (a === "--apply") out.apply = true;
+    else if (a.startsWith("--days=")) out.days = parseInt(a.slice("--days=".length), 10) || 30;
+    else if (a.startsWith("--dir=")) out.dir = a.slice("--dir=".length);
+  }
+  return out;
+}
+
+/** Find the default Claude Code project memory directory for this CWD. */
+function defaultMemoryDir(): string | null {
+  const home = process.env.HOME ?? homedir();
+  const cwd = process.cwd();
+  // Convention: <home>/.claude/projects/<encoded-cwd>/memory/
+  // The encoding replaces / with -, e.g. /Users/masonwyatt/foo → -Users-masonwyatt-foo
+  const encoded = "-" + cwd.replace(/^\//, "").replace(/\//g, "-");
+  const dir = join(home, ".claude", "projects", encoded, "memory");
+  if (existsSync(dir)) return dir;
+  return null;
+}
+
+function listMemoryFiles(dir: string): string[] {
+  return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+}
+
+/** Extract the version-major prefix from a project memory filename. e.g. "project_v123_..." → "v123" */
+function versionPrefix(name: string): string | null {
+  const m = name.match(/^project_v(\d+(?:[a-z\d_]*)?)/i);
+  return m ? `v${m[1]!.split("_")[0]!}` : null;
+}
+
+/** Compare two project memory entries by version prefix (semver-ish). */
+function compareVersions(a: string, b: string): number {
+  // Strip non-digit suffix and compare numerically
+  const an = parseInt(a.replace(/[^\d]/g, ""), 10);
+  const bn = parseInt(b.replace(/[^\d]/g, ""), 10);
+  return an - bn;
+}
+
+function findCandidates(dir: string, days: number): PruneCandidate[] {
+  const files = listMemoryFiles(dir);
+  const now = Date.now();
+  const cutoff = now - days * 24 * 60 * 60 * 1000;
+
+  // Group by major-version prefix
+  const byPrefix = new Map<string, Array<{ file: string; mtime: number }>>();
+  for (const file of files) {
+    const full = join(dir, file);
+    const mtime = statSync(full).mtimeMs;
+    const prefix = versionPrefix(file);
+    if (!prefix) continue;
+    if (!byPrefix.has(prefix)) byPrefix.set(prefix, []);
+    byPrefix.get(prefix)!.push({ file, mtime });
+  }
+
+  // For each prefix group, find the newest version. Older same-prefix files are candidates.
+  const candidates: PruneCandidate[] = [];
+  // Sort prefixes by version number; older versions whose newer-version sibling exists are candidates.
+  const prefixes = [...byPrefix.keys()].sort(compareVersions);
+  for (let i = 0; i < prefixes.length - 1; i++) {
+    const olderPrefix = prefixes[i]!;
+    const newerPrefix = prefixes[i + 1]!;
+    const olderEntries = byPrefix.get(olderPrefix) ?? [];
+    for (const { file, mtime } of olderEntries) {
+      if (mtime > cutoff) continue;
+      const ageDays = Math.round((now - mtime) / (24 * 60 * 60 * 1000));
+      candidates.push({
+        path: join(dir, file),
+        name: file,
+        ageDays,
+        reason: `superseded by ${newerPrefix}_*.md (older than ${days}d cutoff)`,
+      });
+    }
+  }
+
+  // Also flag any file with an explicit "(superseded" marker in its body
+  for (const file of files) {
+    const full = join(dir, file);
+    const mtime = statSync(full).mtimeMs;
+    if (mtime > cutoff) continue;
+    let content = "";
+    try { content = readFileSync(full, "utf-8"); } catch { continue; }
+    if (/\(superseded by/i.test(content) && !candidates.some((c) => c.path === full)) {
+      const ageDays = Math.round((now - mtime) / (24 * 60 * 60 * 1000));
+      candidates.push({
+        path: full,
+        name: file,
+        ageDays,
+        reason: `body contains "(superseded by ...)" marker`,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+function pruneFromIndex(memoryDir: string, removedNames: string[]): number {
+  const indexPath = join(memoryDir, "MEMORY.md");
+  if (!existsSync(indexPath)) return 0;
+  const lines = readFileSync(indexPath, "utf-8").split("\n");
+  const removedSet = new Set(removedNames);
+  const kept: string[] = [];
+  let pruned = 0;
+  for (const line of lines) {
+    const m = line.match(/\(([^)]+\.md)\)/);
+    if (m && removedSet.has(basename(m[1]!))) {
+      pruned++;
+      continue;
+    }
+    kept.push(line);
+  }
+  if (pruned > 0) {
+    writeFileSync(indexPath, kept.join("\n"));
+  }
+  return pruned;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const dir = args.dir ?? defaultMemoryDir();
+  if (!dir || !existsSync(dir)) {
+    process.stderr.write(
+      `prune-old-memories: no memory dir found.\n` +
+      `Try: bun run scripts/prune-old-memories.ts --dir=<path>\n` +
+      `Default location: ~/.claude/projects/<encoded-cwd>/memory/\n`,
+    );
+    process.exit(1);
+  }
+
+  const candidates = findCandidates(dir, args.days);
+
+  if (candidates.length === 0) {
+    process.stdout.write(`prune-old-memories: no candidates older than ${args.days} days found in ${dir}\n`);
+    return;
+  }
+
+  process.stdout.write(`prune-old-memories: ${candidates.length} candidate(s) older than ${args.days} days in:\n`);
+  process.stdout.write(`  ${dir}\n\n`);
+  for (const c of candidates) {
+    process.stdout.write(`  • ${c.name}  (${c.ageDays}d old)\n`);
+    process.stdout.write(`      reason: ${c.reason}\n`);
+  }
+
+  if (!args.apply) {
+    process.stdout.write(`\nDry run — no files removed. Re-run with --apply to delete + remove from MEMORY.md.\n`);
+    return;
+  }
+
+  // Apply mode
+  let removed = 0;
+  const removedNames: string[] = [];
+  for (const c of candidates) {
+    try {
+      unlinkSync(c.path);
+      removed++;
+      removedNames.push(c.name);
+    } catch (e) {
+      process.stderr.write(`  ✗ failed to delete ${c.name}: ${(e as Error).message}\n`);
+    }
+  }
+  const indexPruned = pruneFromIndex(dir, removedNames);
+  process.stdout.write(`\nremoved ${removed} memory file(s); pruned ${indexPruned} MEMORY.md entry(ies).\n`);
+}
+
+if (import.meta.main) {
+  void main();
+}
+
+// Re-export for testing
+export { findCandidates, defaultMemoryDir, parseArgs, versionPrefix };

package/scripts/publish.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Publish ashlr-plugin to GitHub (public) and enable Pages for the /docs site.
+# Also publishes @ashlr/core-efficiency if the sibling repo exists locally and
+# hasn't been pushed yet. Safe to re-run — each step is a no-op if already done.
+#
+# Requires: gh CLI authed (gh auth status).
+# Usage: ./scripts/publish.sh [--dry-run]
+
+set -euo pipefail
+
+DRY_RUN=0
+[ "${1:-}" = "--dry-run" ] && DRY_RUN=1
+
+cyan()   { printf "\033[36m%s\033[0m\n" "$*"; }
+green()  { printf "\033[32m%s\033[0m\n" "$*"; }
+yellow() { printf "\033[33m%s\033[0m\n" "$*"; }
+red()    { printf "\033[31m%s\033[0m\n" "$*"; }
+
+run() {
+  cyan "\$ $*"
+  if [ "$DRY_RUN" -eq 0 ]; then eval "$@"; fi
+}
+
+if ! command -v gh >/dev/null; then
+  red "gh CLI not installed. https://cli.github.com"
+  exit 1
+fi
+
+gh auth status >/dev/null 2>&1 || { red "gh not authed. Run: gh auth login"; exit 1; }
+USER=$(gh api user --jq .login)
+green "Authed as: $USER"
+echo
+
+STACK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CORE_DIR="$(cd "$STACK_DIR/../ashlr-core-efficiency" 2>/dev/null && pwd || true)"
+
+# --- 0. Pre-flight: verify the public manifests agree on the version ---
+yellow "→ Checking version manifest sync…"
+if ! (cd "$STACK_DIR" && bun run version:check); then
+  red "Version manifests are out of sync. Run: bun run version:bump <new-version>"
+  exit 1
+fi
+echo
+
+# --- 1. Publish @ashlr/core-efficiency (public) ---
+if [ -n "$CORE_DIR" ] && [ -d "$CORE_DIR/.git" ]; then
+  cd "$CORE_DIR"
+  if ! git remote get-url origin >/dev/null 2>&1; then
+    yellow "→ ashlr-core-efficiency has no remote. Creating…"
+    run "gh repo create $USER/ashlr-core-efficiency --public --source . --description 'Token-efficiency primitives for Claude Code: genome, compression, provider-aware budgeting.' --push"
+  else
+    green "✓ ashlr-core-efficiency already has remote: $(git remote get-url origin)"
+    run "git push -u origin main 2>/dev/null || git push"
+  fi
+else
+  yellow "⚠ skipping ashlr-core-efficiency — sibling repo not found at $STACK_DIR/../ashlr-core-efficiency"
+fi
+echo
+
+# --- 2. Publish ashlr-plugin ---
+cd "$STACK_DIR"
+if ! git remote get-url origin >/dev/null 2>&1; then
+  yellow "→ ashlr-plugin has no remote. Creating…"
+  run "gh repo create $USER/ashlr-plugin --public --source . --description 'Open-source Claude Code plugin — token-efficient Read/Grep/Edit via @ashlr/core-efficiency. MIT.' --push"
+else
+  green "✓ ashlr-plugin already has remote: $(git remote get-url origin)"
+  run "git push -u origin main 2>/dev/null || git push"
+fi
+echo
+
+# --- 3. Enable GitHub Pages from /docs ---
+yellow "→ Enabling GitHub Pages from /docs folder…"
+PAGES_JSON=$(cat <<EOF
+{"source":{"branch":"main","path":"/docs"}}
+EOF
+)
+run "gh api -X POST /repos/$USER/ashlr-plugin/pages --input - <<< '$PAGES_JSON' 2>/dev/null || gh api -X PUT /repos/$USER/ashlr-plugin/pages --input - <<< '$PAGES_JSON' 2>/dev/null || echo '(pages may already be enabled)'"
+echo
+
+# --- 4. Report final URLs ---
+green "Done."
+echo "  Plugin repo:        https://github.com/$USER/ashlr-plugin"
+echo "  Landing page:       https://plugin.ashlr.ai/"
+echo "  Core library repo:  https://github.com/$USER/ashlr-core-efficiency"
+echo
+yellow "Install inside Claude Code:"
+echo "  /plugin marketplace add $USER/ashlr-plugin"
+echo "  /plugin install ashlr@ashlr-marketplace"

package/scripts/read-calibration.ts

@@ -0,0 +1,122 @@
+/**
+ * read-calibration — loads the empirical grep multiplier from
+ * ~/.ashlr/calibration.json (written by scripts/calibrate-grep.ts).
+ *
+ * Exports `getCalibrationMultiplier()` which efficiency-server.ts calls when
+ * computing the "tokens saved" credit for genome-routed greps.
+ *
+ * Caching: the result is memoized for the process lifetime. The calibration
+ * file is written rarely (only when the user explicitly runs calibrate-grep),
+ * so re-reading on every tool call is wasteful.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// Use process.env.HOME when set so test subprocesses on Windows can override
+// the home directory (os.homedir() on Windows reads USERPROFILE, not HOME).
+export const CALIBRATION_PATH = join(
+  process.env.HOME ?? homedir(),
+  ".ashlr",
+  "calibration.json",
+);
+
+/** Default when no calibration has been run — conservative guess. */
+export const DEFAULT_MULTIPLIER = 4;
+
+export interface CalibrationFile {
+  updatedAt: string;
+  samples: CalibrationSample[];
+  meanRatio: number;
+  p50: number;
+  p90: number;
+  /** Mean ratio across only pattern-matched genome retrievals (excludes core-fallback + synthetic). */
+  measuredMean?: number;
+  /** Mean ratio across synthetic-only samples (no genome hit). */
+  syntheticMean?: number;
+  /** Number of samples that used a real pattern-matched genome retrieval. */
+  measuredCount?: number;
+  /** Mean ratio across core-fallback samples (genome present but pattern scored 0; constant-core output). */
+  coreFallbackMean?: number;
+  /** Number of samples that hit the core-fallback path. */
+  coreFallbackCount?: number;
+}
+
+export interface CalibrationSample {
+  cwd: string;
+  pattern: string;
+  rawBytes: number;
+  compressedBytes: number;
+  ratio: number;
+  /**
+   * "measured" — pattern scored > 0 against genome sections; compressedBytes is the real retrieval output.
+   * "core-fallback" — pattern scored 0; compressedBytes is the constant core-section output (north-star + milestone).
+   *   Reflects real ashlr__grep behavior for non-matching queries, but the ratio is dominated by the constant
+   *   numerator, not pattern-specific compression.
+   * "synthetic" — no genome present at all; compressedBytes = rawBytes / 4 (estimate, ratio always 4.0).
+   */
+  quality: "measured" | "core-fallback" | "synthetic";
+}
+
+// In-process cache so we pay the file read exactly once per MCP server
+// lifetime. Set to `null` to force a re-read (tests can clear this).
+let _cached: number | null = null;
+
+/**
+ * Returns the empirical mean ratio from ~/.ashlr/calibration.json, or
+ * DEFAULT_MULTIPLIER if the file is absent or malformed.
+ *
+ * The returned value is the multiplier applied to the genome-compressed output
+ * size to estimate what full ripgrep output would have cost.
+ */
+export function getCalibrationMultiplier(
+  calibrationPath: string = CALIBRATION_PATH,
+): number {
+  // Return memoized value if already loaded (and using default path).
+  if (_cached !== null && calibrationPath === CALIBRATION_PATH) {
+    return _cached;
+  }
+
+  try {
+    if (!existsSync(calibrationPath)) {
+      _cached = DEFAULT_MULTIPLIER;
+      return DEFAULT_MULTIPLIER;
+    }
+    const raw = readFileSync(calibrationPath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      typeof (parsed as Record<string, unknown>).meanRatio !== "number" ||
+      !Number.isFinite((parsed as Record<string, unknown>).meanRatio as number) ||
+      ((parsed as Record<string, unknown>).meanRatio as number) <= 0
+    ) {
+      _cached = DEFAULT_MULTIPLIER;
+      return DEFAULT_MULTIPLIER;
+    }
+    const file = parsed as CalibrationFile;
+    // Preference order:
+    //   1. measuredMean      — pattern-matched genome retrievals (best signal)
+    //   2. coreFallbackMean  — real ashlr__grep output for non-matching queries
+    //                          (still a measurement, just of the constant-core path)
+    //   3. meanRatio         — overall, may be diluted by synthetic 4× estimates
+    const isUsable = (n: unknown): n is number =>
+      typeof n === "number" && Number.isFinite(n) && (n as number) > 0;
+    const ratio = isUsable(file.measuredMean) && (file.measuredCount ?? 0) > 0
+      ? file.measuredMean
+      : isUsable(file.coreFallbackMean) && (file.coreFallbackCount ?? 0) > 0
+        ? file.coreFallbackMean
+        : file.meanRatio;
+    if (calibrationPath === CALIBRATION_PATH) _cached = ratio;
+    return ratio;
+  } catch {
+    if (calibrationPath === CALIBRATION_PATH) _cached = DEFAULT_MULTIPLIER;
+    return DEFAULT_MULTIPLIER;
+  }
+}
+
+/** Clear the in-process cache (useful in tests). */
+export function clearCalibrationCache(): void {
+  _cached = null;
+}