ashlr-plugin 1.36.4

package/servers/_manifest-v2.ts

@@ -0,0 +1,447 @@
+/**
+ * _manifest-v2.ts — Genome 2.0 manifest schema (additive, backward-compatible).
+ *
+ * v1 (core-efficiency) → v2 (this module) is purely ADDITIVE:
+ *   - All v1 fields remain canonical and unchanged.
+ *   - Section meta gains three optional freshness fields:
+ *       lastUpdatedAt — ISO timestamp of last refresh (mirrors updatedAt for v1)
+ *       sourceTrust   — "static" | "commit" | "pr" | "issue" | "test"
+ *       confidence    — 0..1 float (heuristic, optional)
+ *   - A new section type is introduced for commit-diff awareness:
+ *       commit sections live at `commits/<sha>.json` (not markdown) and carry
+ *       structured CommitSection metadata in addition to the SectionMeta entry.
+ *   - schemaVersion is bumped to 2. v1 manifests auto-upgrade IN-MEMORY on load
+ *     and persist v2 on the next write. v1 readers will still parse v2 because
+ *     the only new top-level field is the optional `schemaVersion`; v1 keys
+ *     (`version`, `project`, `sections`, etc.) remain untouched.
+ *
+ * This module deliberately does NOT modify `node_modules/@ashlr/core-efficiency`.
+ * It wraps the loader so existing call sites keep working with `loadManifest`
+ * from core-efficiency and only opt-in to v2 by going through
+ * `loadManifestV2` / `saveManifestV2` here.
+ */
+
+import { existsSync } from "fs";
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import {
+  type GenomeManifest as GenomeManifestV1,
+  type SectionMeta as SectionMetaV1,
+  manifestPath,
+} from "@ashlr/core-efficiency/genome";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SourceTrust = "static" | "commit" | "pr" | "issue" | "test" | "synthesis";
+
+/** v2 SectionMeta — adds freshness metadata. All new fields are optional. */
+export interface SectionMetaV2 extends SectionMetaV1 {
+  /** ISO timestamp of the most recent refresh. Mirrors updatedAt by default. */
+  lastUpdatedAt?: string;
+  /** Where this section's content was derived from. Defaults to "static". */
+  sourceTrust?: SourceTrust;
+  /** Heuristic 0..1 — higher = more trustworthy. Defaults unset. */
+  confidence?: number;
+  /**
+   * Marker so retrieval can distinguish section kinds.
+   *
+   * Q3 added "pr" + "issue" — cloud-sync'd genome deltas from GitHub
+   * webhooks. Older v2 manifests written before Q3 don't carry these and
+   * default to "static" via upgradeManifest().
+   */
+  kind?: "commit" | "static" | "discovery" | "pr" | "issue";
+}
+
+/**
+ * Commit section payload — stored at `.ashlrcode/genome/commits/<sha>.json`.
+ * The manifest also gets a SectionMetaV2 entry pointing at this file with
+ * `kind: "commit"` and `sourceTrust: "commit"`.
+ */
+export interface CommitSection {
+  /** Full git SHA. */
+  sha: string;
+  /** Commit subject + body (raw, untruncated). */
+  message: string;
+  /** Author "Name <email>" line from `git show --pretty=fuller`. */
+  author: string;
+  /** ISO timestamp of the commit (author date). */
+  date: string;
+  /** Files changed in this commit (relative paths from repo root). */
+  filesChanged: string[];
+  /** Markdown body — typically a short summary + diff highlights. */
+  summary: string;
+}
+
+export interface GenomeManifestV2 extends Omit<GenomeManifestV1, "version"> {
+  /** v1 manifests have `version: 1`. v2 manifests carry both for compat. */
+  version: 1;
+  /** v2 schema marker. Absent on v1 manifests on disk. */
+  schemaVersion?: 2;
+  sections: SectionMetaV2[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Subdirectory under .ashlrcode/genome/ where commit sections live. */
+export const COMMITS_SUBDIR = "commits";
+
+/** Hard cap on commit sections kept on disk. Older ones are pruned. */
+export const COMMIT_RETENTION_LIMIT = 50;
+
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Upgrade a v1 manifest to v2 in-memory.
+ * Idempotent — running on an already-v2 manifest is a no-op.
+ *
+ * Sets defaults for each section:
+ *   - lastUpdatedAt ← updatedAt
+ *   - sourceTrust   ← "static"
+ *   - kind          ← "static"
+ *
+ * The original `updatedAt` field is preserved so v1 readers stay happy.
+ */
+export function upgradeManifest(manifest: GenomeManifestV1 | GenomeManifestV2): GenomeManifestV2 {
+  const m = manifest as GenomeManifestV2;
+  if (m.schemaVersion === 2) {
+    // Already v2 — still backfill any missing per-section defaults so old v2
+    // manifests written before this defaulting existed pick up the fields.
+    for (const s of m.sections) {
+      if (!s.lastUpdatedAt) s.lastUpdatedAt = s.updatedAt;
+      if (!s.sourceTrust) s.sourceTrust = s.kind === "commit" ? "commit" : "static";
+      if (!s.kind) s.kind = "static";
+    }
+    return m;
+  }
+
+  // True v1 → v2 upgrade.
+  const upgraded: GenomeManifestV2 = {
+    ...(manifest as GenomeManifestV1),
+    schemaVersion: 2,
+    sections: (manifest.sections as SectionMetaV1[]).map((s) => ({
+      ...s,
+      lastUpdatedAt: (s as SectionMetaV2).lastUpdatedAt ?? s.updatedAt,
+      sourceTrust: (s as SectionMetaV2).sourceTrust ?? "static",
+      kind: (s as SectionMetaV2).kind ?? "static",
+    })),
+  };
+  return upgraded;
+}
+
+// ---------------------------------------------------------------------------
+// Load / Save (v2-aware)
+// ---------------------------------------------------------------------------
+
+export async function loadManifestV2(cwd: string): Promise<GenomeManifestV2 | null> {
+  const p = manifestPath(cwd);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = await readFile(p, "utf-8");
+    const parsed = JSON.parse(raw) as GenomeManifestV1 | GenomeManifestV2;
+    return upgradeManifest(parsed);
+  } catch {
+    // Corrupt / partial — treat as missing, same policy as v1 loader.
+    return null;
+  }
+}
+
+export async function saveManifestV2(cwd: string, manifest: GenomeManifestV2): Promise<void> {
+  const target = manifestPath(cwd);
+  const dir = dirname(target);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  manifest.updatedAt = new Date().toISOString();
+  if (!manifest.schemaVersion) manifest.schemaVersion = 2;
+  const tmp = target + ".tmp";
+  try {
+    await writeFile(tmp, JSON.stringify(manifest, null, 2), "utf-8");
+    await rename(tmp, target);
+  } catch (e) {
+    const { unlink } = await import("fs/promises");
+    await unlink(tmp).catch(() => {});
+    throw e;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commit-section file helpers
+// ---------------------------------------------------------------------------
+
+export function commitsDir(cwd: string): string {
+  return join(cwd, ".ashlrcode", "genome", COMMITS_SUBDIR);
+}
+
+export function commitSectionPath(cwd: string, sha: string): string {
+  // Relative path INSIDE the genome dir (matches SectionMetaV2.path convention).
+  return join(COMMITS_SUBDIR, `${sha}.json`);
+}
+
+export function commitSectionAbsPath(cwd: string, sha: string): string {
+  return join(commitsDir(cwd), `${sha}.json`);
+}
+
+/**
+ * Write a commit section JSON file (separate from the manifest update).
+ * Returns the relative path stored in the manifest's `sections[].path`.
+ */
+export async function writeCommitSectionFile(
+  cwd: string,
+  payload: CommitSection,
+): Promise<string> {
+  const abs = commitSectionAbsPath(cwd, payload.sha);
+  const dir = dirname(abs);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(abs, JSON.stringify(payload, null, 2), "utf-8");
+  return commitSectionPath(cwd, payload.sha);
+}
+
+export async function readCommitSectionFile(
+  cwd: string,
+  sha: string,
+): Promise<CommitSection | null> {
+  const abs = commitSectionAbsPath(cwd, sha);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = await readFile(abs, "utf-8");
+    return JSON.parse(raw) as CommitSection;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discovery sections (Q2 AI-Native Synthesis)
+// ---------------------------------------------------------------------------
+
+/** Subdirectory under .ashlrcode/genome/ where discovery sections live. */
+export const DISCOVERIES_SUBDIR = "discoveries";
+
+/** Hard cap on discovery sections kept on disk. Older ones are pruned. */
+export const DISCOVERY_RETENTION_LIMIT = 30;
+
+/** Evidence anchor for a discovery — points back at concrete code or files. */
+export interface DiscoveryEvidence {
+  path: string;
+  lineRange?: [number, number];
+}
+
+/**
+ * Discovery section payload — stored at
+ * `.ashlrcode/genome/discoveries/<id>.json`. The manifest also gets a
+ * SectionMetaV2 entry pointing at this file with `kind: "discovery"` and
+ * `sourceTrust: "synthesis"`.
+ *
+ * Discoveries are AI-synthesized insights ("3 files use this util wrong",
+ * "auth refactor introduced a flaky test pattern"). Lower-confidence than
+ * commit sections (which are straight from git) but still actionable.
+ */
+export interface DiscoverySection {
+  /** Stable ID — hash of summary + sourceCommits, used as filename. */
+  id: string;
+  /** 1-2 sentence insight written by the synthesizer. */
+  summary: string;
+  /** Anchors to concrete code — paths + optional line ranges. */
+  evidence: DiscoveryEvidence[];
+  /** SHAs of commit sections that inspired this discovery. */
+  sourceCommits: string[];
+  /** ISO timestamp of when the synthesizer produced this. */
+  synthesizedAt: string;
+  /** 0..1 confidence set by the synthesizer (LLM-self-reported, clamped). */
+  confidence: number;
+}
+
+export function discoveriesDir(cwd: string): string {
+  return join(cwd, ".ashlrcode", "genome", DISCOVERIES_SUBDIR);
+}
+
+export function discoverySectionPath(_cwd: string, id: string): string {
+  return join(DISCOVERIES_SUBDIR, `${id}.json`);
+}
+
+export function discoverySectionAbsPath(cwd: string, id: string): string {
+  return join(discoveriesDir(cwd), `${id}.json`);
+}
+
+/**
+ * Write a discovery section JSON file (separate from the manifest update).
+ * Returns the relative path stored in the manifest's `sections[].path`.
+ */
+export async function writeDiscoverySectionFile(
+  cwd: string,
+  payload: DiscoverySection,
+): Promise<string> {
+  const abs = discoverySectionAbsPath(cwd, payload.id);
+  const dir = dirname(abs);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(abs, JSON.stringify(payload, null, 2), "utf-8");
+  return discoverySectionPath(cwd, payload.id);
+}
+
+export async function readDiscoverySectionFile(
+  cwd: string,
+  id: string,
+): Promise<DiscoverySection | null> {
+  const abs = discoverySectionAbsPath(cwd, id);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = await readFile(abs, "utf-8");
+    return JSON.parse(raw) as DiscoverySection;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PR sections (Q3 PR/Issue Retrieval)
+// ---------------------------------------------------------------------------
+
+/** Subdirectory under .ashlrcode/genome/sections/ where PR sections live. */
+export const PRS_SUBDIR = "prs";
+
+/** Hard cap on PR sections kept on disk. Older ones are pruned by mtime. */
+export const PR_RETENTION_LIMIT = 100;
+
+/**
+ * PR section payload — stored at `.ashlrcode/genome/sections/prs/<number>.json`.
+ * Populated from `pr_merged` deltas via genome-cloud-sync. The manifest carries
+ * a parallel SectionMetaV2 entry with `kind: "pr"` + `sourceTrust: "pr"`.
+ *
+ * Privacy: title + summary are already truncated server-side; no diffs.
+ */
+export interface PrSection {
+  /** PR number as a string id (matches sourceSha in the cloud delta). */
+  id: string;
+  /** PR title (already truncated to 512 chars by the webhook handler). */
+  title: string;
+  /** ISO timestamp when the PR merged. May be empty for backfilled rows. */
+  mergedAt: string;
+  /** GitHub login of the PR author. May be empty. */
+  author: string;
+  /** Paths only — webhook never ships diff content. May be empty. */
+  filesChanged: string[];
+  /** 2-3 sentence body summary, already truncated to 1024 chars. */
+  summary: string;
+  /** Canonical https://github.com/<owner>/<repo>/pull/<n> URL. */
+  url: string;
+}
+
+export function prsDir(cwd: string): string {
+  return join(cwd, ".ashlrcode", "genome", "sections", PRS_SUBDIR);
+}
+
+export function prSectionPath(_cwd: string, id: string): string {
+  return join("sections", PRS_SUBDIR, `${id}.json`);
+}
+
+export function prSectionAbsPath(cwd: string, id: string): string {
+  return join(prsDir(cwd), `${id}.json`);
+}
+
+export async function writePrSectionFile(
+  cwd: string,
+  payload: PrSection,
+): Promise<string> {
+  const abs = prSectionAbsPath(cwd, payload.id);
+  const dir = dirname(abs);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(abs, JSON.stringify(payload, null, 2), "utf-8");
+  return prSectionPath(cwd, payload.id);
+}
+
+export async function readPrSectionFile(
+  cwd: string,
+  id: string,
+): Promise<PrSection | null> {
+  const abs = prSectionAbsPath(cwd, id);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = await readFile(abs, "utf-8");
+    return JSON.parse(raw) as PrSection;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Issue sections (Q3 PR/Issue Retrieval)
+// ---------------------------------------------------------------------------
+
+/** Subdirectory under .ashlrcode/genome/sections/ where Issue sections live. */
+export const ISSUES_SUBDIR = "issues";
+
+/** Hard cap on Issue sections kept on disk. Older ones are pruned by mtime. */
+export const ISSUE_RETENTION_LIMIT = 100;
+
+/**
+ * Issue section payload — stored at
+ * `.ashlrcode/genome/sections/issues/<number>.json`. Populated from
+ * `issue_closed` deltas via genome-cloud-sync.
+ */
+export interface IssueSection {
+  /** Issue number as a string id. */
+  id: string;
+  /** Issue title (already truncated to 512 chars). */
+  title: string;
+  /** ISO timestamp when the issue was closed. May be empty. */
+  closedAt: string;
+  /** GitHub login of the issue author. May be empty. */
+  author: string;
+  /** Issue labels — currently empty (webhook does not yet ship labels). */
+  labels: string[];
+  /** Issue body summary, truncated to 1024 chars. */
+  summary: string;
+  /** Canonical https://github.com/<owner>/<repo>/issues/<n> URL. */
+  url: string;
+}
+
+export function issuesDir(cwd: string): string {
+  return join(cwd, ".ashlrcode", "genome", "sections", ISSUES_SUBDIR);
+}
+
+export function issueSectionPath(_cwd: string, id: string): string {
+  return join("sections", ISSUES_SUBDIR, `${id}.json`);
+}
+
+export function issueSectionAbsPath(cwd: string, id: string): string {
+  return join(issuesDir(cwd), `${id}.json`);
+}
+
+export async function writeIssueSectionFile(
+  cwd: string,
+  payload: IssueSection,
+): Promise<string> {
+  const abs = issueSectionAbsPath(cwd, payload.id);
+  const dir = dirname(abs);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(abs, JSON.stringify(payload, null, 2), "utf-8");
+  return issueSectionPath(cwd, payload.id);
+}
+
+export async function readIssueSectionFile(
+  cwd: string,
+  id: string,
+): Promise<IssueSection | null> {
+  const abs = issueSectionAbsPath(cwd, id);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = await readFile(abs, "utf-8");
+    return JSON.parse(raw) as IssueSection;
+  } catch {
+    return null;
+  }
+}

package/servers/_mcp-host.ts

@@ -0,0 +1,93 @@
+/**
+ * Multi-host MCP detection.
+ *
+ * The ashlr MCP server is consumable from any MCP-capable host (Claude Code,
+ * Cline, Claude Desktop, OpenAI Codex CLI, …). Most behavior is host-agnostic:
+ *  - tool dispatch, snipCompact, genome retrieval, stats accounting all work
+ *    regardless of who's calling.
+ *  - PPID-derived session id (see `_stats.ts::ppidSessionId`) covers any host
+ *    that doesn't forward `CLAUDE_SESSION_ID`.
+ *  - `existsSync` guards on `~/.claude/` paths mean missing-CC-dirs are a
+ *    no-op rather than a crash.
+ *
+ * But a few code paths are Claude-Code-specific (hook firing, status-line
+ * rendering, OAuth-token harvest from `~/.claude/.credentials.json`). The
+ * `ASHLR_MCP_HOST` env var declares which host launched us so those code
+ * paths can short-circuit cleanly when running under a non-CC host.
+ *
+ * Each host's MCP server config sets the env var:
+ *
+ *   Claude Code  (default, no change needed)  → undefined or "claude-code"
+ *   Cline (cline_mcp_settings.json)           → "cline"
+ *   Claude Desktop (claude_desktop_config.json) → "claude-desktop"
+ *   Codex CLI (~/.codex/config.toml)          → "codex-cli"
+ *   Anything else                              → "generic"
+ *
+ * Backwards compat: when unset, we infer "claude-code" so existing installs
+ * keep their exact current behavior. The audit covered every gate; none of
+ * them change behavior when the env var is absent.
+ */
+
+export type McpHost =
+  | "claude-code"
+  | "cline"
+  | "claude-desktop"
+  | "codex-cli"
+  | "generic";
+
+const KNOWN_HOSTS: ReadonlySet<McpHost> = new Set([
+  "claude-code",
+  "cline",
+  "claude-desktop",
+  "codex-cli",
+  "generic",
+]);
+
+/**
+ * Resolve which MCP host launched this process.
+ *
+ * Precedence:
+ *   1. `ASHLR_MCP_HOST` env var (explicit, set by each host's config snippet).
+ *   2. Presence of `CLAUDE_SESSION_ID` or `CLAUDE_PLUGIN_ROOT` → "claude-code"
+ *      (covers the default Claude Code install path so users who don't set
+ *      the env var still see the original behavior).
+ *   3. Fallback "generic" — safe default; disables CC-only side effects.
+ *
+ * Never throws; never reads files; never logs. Cheap to call repeatedly.
+ */
+export function detectMcpHost(env: NodeJS.ProcessEnv = process.env): McpHost {
+  const explicit = env.ASHLR_MCP_HOST?.trim().toLowerCase();
+  if (explicit && KNOWN_HOSTS.has(explicit as McpHost)) {
+    return explicit as McpHost;
+  }
+  // Inference: any of these signals → Claude Code (preserves existing
+  // behavior for users who haven't set ASHLR_MCP_HOST).
+  if (
+    (env.CLAUDE_SESSION_ID && env.CLAUDE_SESSION_ID.trim().length > 0) ||
+    (env.CLAUDE_PLUGIN_ROOT && env.CLAUDE_PLUGIN_ROOT.trim().length > 0) ||
+    (env.CLAUDE_CODE_MODEL && env.CLAUDE_CODE_MODEL.trim().length > 0)
+  ) {
+    return "claude-code";
+  }
+  // Generic is the safe non-CC default: hooks/status-line code paths
+  // short-circuit; stats + genome + dispatch still work normally.
+  return "generic";
+}
+
+/** Convenience: are we running inside Claude Code (the default host)? */
+export function isClaudeCodeHost(env: NodeJS.ProcessEnv = process.env): boolean {
+  return detectMcpHost(env) === "claude-code";
+}
+
+/**
+ * Convenience: should we skip Claude-Code-specific side effects?
+ * Returns true for every non-CC host. Used by:
+ *  - status-line install nudges (other hosts have their own UI)
+ *  - `~/.claude/settings.json` writes (other hosts use their own config)
+ *  - hook-firing assumptions (only CC fires PreToolUse/SessionEnd hooks)
+ */
+export function skipClaudeCodeSideEffects(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return detectMcpHost(env) !== "claude-code";
+}