supipowers 1.5.3 → 2.0.1

package/src/lsp/capabilities.ts

@@ -0,0 +1,108 @@
+// src/lsp/capabilities.ts
+//
+// Probe the active LSP server's capabilities once per gate run.
+// Used to short-circuit diagnostic collection (and any future capability-
+// gated workflow) when the server has no `textDocument/diagnostic` support,
+// instead of failing the gate on a vacuous error.
+//
+// The probe asks an agent to invoke the lsp tool with action "capabilities"
+// (introduced in OMP 14.5.13) and emit a tiny JSON record summarizing which
+// methods at least one active server advertises. Failure to probe is
+// treated as fail-closed: NO_LSP_SUPPORT (gate skips rather than pretending
+// it ran).
+
+import { Type, type Static } from "@sinclair/typebox";
+import {
+  parseStructuredOutput,
+  runWithOutputValidation,
+  type ReliabilityReporter,
+} from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
+import type { GateExecutionContext } from "../types.js";
+
+export const LspCapabilitiesSchema = Type.Object(
+  {
+    diagnostics: Type.Boolean(),
+    references: Type.Boolean(),
+    definition: Type.Boolean(),
+    hover: Type.Boolean(),
+    rename: Type.Boolean(),
+  },
+  { additionalProperties: false },
+);
+
+export type LspCapabilities = Static<typeof LspCapabilitiesSchema>;
+
+const SCHEMA_TEXT = renderSchemaText(LspCapabilitiesSchema);
+
+const PROBE_PROMPT = [
+  "You are probing LSP server capabilities for a quality gate.",
+  'Run the lsp tool with action: "capabilities" and file: "*".',
+  "Examine the returned capabilities and emit JSON only matching this schema:",
+  SCHEMA_TEXT,
+  "",
+  "Rules:",
+  "- `diagnostics`: true when at least one server advertises `textDocument/diagnostic` or `textDocument/publishDiagnostics` support.",
+  "- `references`: true when at least one server advertises `textDocument/references`.",
+  "- `definition`, `hover`, `rename`: same pattern for their LSP method names.",
+  "- Use `false` when the capability is missing, not when you are unsure.",
+  "- Do not wrap the JSON in markdown fences.",
+].join("\n");
+
+/** Pessimistic default: every capability is missing. Used as fail-closed
+ *  fallback when the probe itself fails or returns blocked. */
+export const NO_LSP_SUPPORT: LspCapabilities = {
+  diagnostics: false,
+  references: false,
+  definition: false,
+  hover: false,
+  rename: false,
+};
+
+/** Optimistic default: every capability advertised. Used by tests and as a
+ *  reference shape for the probe contract. */
+export const FULL_LSP_SUPPORT: LspCapabilities = {
+  diagnostics: true,
+  references: true,
+  definition: true,
+  hover: true,
+  rename: true,
+};
+
+export interface ProbeLspCapabilitiesOptions {
+  cwd: string;
+  createAgentSession: GateExecutionContext["createAgentSession"];
+  reviewModel?: GateExecutionContext["reviewModel"];
+  reliability?: ReliabilityReporter;
+}
+
+/**
+ * Probe LSP capabilities. Returns NO_LSP_SUPPORT when the probe blocks or
+ * throws — callers must treat unknown as unsupported and skip cleanly
+ * rather than running a workflow that depends on the missing capability.
+ */
+export async function probeLspCapabilities(
+  options: ProbeLspCapabilitiesOptions,
+): Promise<LspCapabilities> {
+  try {
+    const result = await runWithOutputValidation<LspCapabilities>(
+      options.createAgentSession,
+      {
+        cwd: options.cwd,
+        prompt: PROBE_PROMPT,
+        schema: SCHEMA_TEXT,
+        parse: (raw) => parseStructuredOutput<LspCapabilities>(raw, LspCapabilitiesSchema),
+        model: options.reviewModel?.model,
+        thinkingLevel: options.reviewModel?.thinkingLevel ?? null,
+        timeoutMs: 60_000,
+        reliability: options.reliability,
+      },
+    );
+    if (result.status === "blocked") {
+      return NO_LSP_SUPPORT;
+    }
+    return result.output;
+  } catch {
+    return NO_LSP_SUPPORT;
+  }
+}

package/src/lsp/contracts.ts

@@ -0,0 +1,35 @@
+// src/lsp/contracts.ts
+//
+// TypeBox contract for the LSP diagnostics agent flow. Consumed by
+// ai/structured-output.ts to schema-check model output and by
+// ai/schema-text.ts to render the shape into the prompt.
+
+import { Type, type Static } from "@sinclair/typebox";
+
+const DIAGNOSTIC_SEVERITIES = ["error", "warning", "info", "hint"] as const;
+
+export const LspDiagnosticSchema = Type.Object(
+  {
+    severity: Type.Union(
+      DIAGNOSTIC_SEVERITIES.map((value) => Type.Literal(value)),
+    ),
+    message: Type.String(),
+    line: Type.Number(),
+    column: Type.Number(),
+  },
+  { additionalProperties: false },
+);
+
+export const LspDiagnosticsResultSchema = Type.Object(
+  {
+    file: Type.String(),
+    diagnostics: Type.Array(LspDiagnosticSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const LspDiagnosticsResultsSchema = Type.Array(LspDiagnosticsResultSchema);
+
+export type LspDiagnostic = Static<typeof LspDiagnosticSchema>;
+export type LspDiagnosticsResult = Static<typeof LspDiagnosticsResultSchema>;
+export type LspDiagnosticsResults = Static<typeof LspDiagnosticsResultsSchema>;

package/src/lsp/detector.ts

@@ -1,4 +1,5 @@
 // src/lsp/detector.ts
+import { findExecutable } from "../utils/executable.js";
 import { LSP_SERVERS, type LspServerEntry } from "./setup-guide.js";
 
 export interface LspServerStatus {
@@ -7,21 +8,16 @@ export interface LspServerStatus {
 }
 
 /**
- * Check which LSP servers are installed by looking for their binaries.
+ * Check which LSP servers are installed by looking for their binaries on PATH.
  */
 export async function checkInstalledServers(
-  exec: (cmd: string, args: string[]) => Promise<{ stdout: string; code: number }>
+  _exec: (cmd: string, args: string[]) => Promise<{ stdout: string; code: number }>,
+  resolveExecutable: (command: string) => string | null = (command) => findExecutable(command),
 ): Promise<LspServerStatus[]> {
-  const results: LspServerStatus[] = [];
-  for (const server of LSP_SERVERS) {
-    try {
-      const result = await exec("which", [server.server]);
-      results.push({ server, installed: result.code === 0 });
-    } catch {
-      results.push({ server, installed: false });
-    }
-  }
-  return results;
+  return LSP_SERVERS.map((server) => ({
+    server,
+    installed: resolveExecutable(server.server) !== null,
+  }));
 }
 
 /**

package/src/markdown-frontmatter.ts

@@ -0,0 +1,68 @@
+import { parse as parseYaml } from "yaml";
+import { normalizeLineEndings } from "./text.js";
+
+export type MarkdownFrontmatterErrorCode =
+  | "missing-frontmatter"
+  | "invalid-frontmatter"
+  | "empty-body";
+
+export class MarkdownFrontmatterError extends Error {
+  constructor(
+    public readonly code: MarkdownFrontmatterErrorCode,
+    public readonly filePath: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "MarkdownFrontmatterError";
+  }
+}
+
+export interface ParsedMarkdownFrontmatter {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseMarkdownFrontmatter(content: string, filePath: string): ParsedMarkdownFrontmatter {
+  const normalized = normalizeLineEndings(content);
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new MarkdownFrontmatterError(
+      "missing-frontmatter",
+      filePath,
+      `${filePath} is missing YAML frontmatter.`,
+    );
+  }
+
+  let frontmatter: unknown;
+  try {
+    frontmatter = parseYaml(match[1]);
+  } catch (error) {
+    throw new MarkdownFrontmatterError(
+      "invalid-frontmatter",
+      filePath,
+      `Invalid YAML frontmatter in ${filePath}: ${(error as Error).message}`,
+    );
+  }
+
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    throw new MarkdownFrontmatterError(
+      "invalid-frontmatter",
+      filePath,
+      `Invalid YAML frontmatter in ${filePath}: frontmatter must be a mapping.`,
+    );
+  }
+
+  const body = match[2]?.trim() ?? "";
+  if (!body) {
+    throw new MarkdownFrontmatterError(
+      "empty-body",
+      filePath,
+      `${filePath} has an empty prompt body.`,
+    );
+  }
+
+  return {
+    frontmatter: frontmatter as Record<string, unknown>,
+    body,
+  };
+}

package/src/mempalace/bridge.ts

@@ -0,0 +1,135 @@
+import type { ResolvedMempalaceConfig } from "./config.js";
+import type { MempalaceParams } from "./schema.js";
+import {
+  resolveBridgeScriptPath,
+  resolveManagedVenvPaths,
+  runBridgeRequest,
+  type BridgePathResult,
+  type MempalaceRuntimeError,
+  type RunBridgeRequestOptions,
+  type RunBridgeRequestResult,
+} from "./runtime.js";
+
+export type MempalaceBridgeCallResult =
+  | {
+      ok: true;
+      action: MempalaceParams["action"];
+      result: unknown;
+      diagnostics: Record<string, unknown>;
+    }
+  | {
+      ok: false;
+      action: MempalaceParams["action"];
+      error: MempalaceRuntimeError;
+      diagnostics: Record<string, unknown>;
+    };
+
+export interface MempalaceBridgeRuntimeDeps {
+  resolveBridgeScriptPath?: () => BridgePathResult;
+  runBridgeRequest?: (options: RunBridgeRequestOptions) => Promise<RunBridgeRequestResult>;
+}
+
+export interface CreateMempalaceBridgeOptions {
+  cwd: string;
+  config: ResolvedMempalaceConfig;
+  runtime?: MempalaceBridgeRuntimeDeps;
+}
+
+export interface MempalaceBridgeFacade {
+  execute(params: MempalaceParams): Promise<MempalaceBridgeCallResult>;
+}
+
+function withSetupRemediation(error: MempalaceRuntimeError): MempalaceRuntimeError {
+  if (error.remediation) return error;
+  if (error.code === "mempalace_missing" || error.code === "bridge_process_failed") {
+    return {
+      ...error,
+      remediation: "Call mempalace(action=\"setup\") first, then retry the requested MemPalace action.",
+    };
+  }
+  return error;
+}
+
+function mergeDiagnostics(...parts: Array<Record<string, unknown> | undefined>): Record<string, unknown> {
+  return Object.assign({}, ...parts.filter(Boolean));
+}
+
+function resolveToolTimeoutMs(params: MempalaceParams, bridgeTimeoutMs: number): number {
+  if (typeof params.timeout !== "number") return bridgeTimeoutMs;
+
+  // Public tool schemas express timeouts in seconds, matching the rest of the
+  // OMP tool surface. The bridge runner uses milliseconds internally.
+  return Math.min(params.timeout * 1000, bridgeTimeoutMs);
+}
+
+export function createMempalaceBridge(options: CreateMempalaceBridgeOptions): MempalaceBridgeFacade {
+  const resolveBridge = options.runtime?.resolveBridgeScriptPath ?? (() => resolveBridgeScriptPath());
+  const runBridge = options.runtime?.runBridgeRequest ?? runBridgeRequest;
+
+  return {
+    async execute(params: MempalaceParams): Promise<MempalaceBridgeCallResult> {
+      const bridgePath = resolveBridge();
+      if (!bridgePath.ok) {
+        return {
+          ok: false,
+          action: params.action,
+          error: bridgePath.error,
+          diagnostics: { bridgeScriptPath: bridgePath.path },
+        };
+      }
+
+      const venv = resolveManagedVenvPaths(options.config.managedVenvPath);
+      const timeoutMs = resolveToolTimeoutMs(params, options.config.timeouts.bridgeMs);
+      const palacePath = params.palace ?? options.config.palacePath;
+      const runResult = await runBridge({
+        pythonPath: venv.python,
+        bridgeScriptPath: bridgePath.path,
+        timeoutMs,
+        request: {
+          action: params.action,
+          params: { ...params },
+          options: {
+            cwd: options.cwd,
+            palacePath,
+            agentName: options.config.defaultAgentName,
+          },
+        },
+      });
+
+      if (!runResult.ok) {
+        return {
+          ok: false,
+          action: params.action,
+          error: withSetupRemediation(runResult.error),
+          diagnostics: {
+            durationMs: runResult.durationMs,
+            stdoutPreview: runResult.stdoutPreview,
+            stderrTail: runResult.stderrTail,
+          },
+        };
+      }
+
+      if (!runResult.response.ok) {
+        return {
+          ok: false,
+          action: params.action,
+          error: withSetupRemediation(runResult.response.error),
+          diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
+            durationMs: runResult.durationMs,
+            stderr: runResult.stderr,
+          }),
+        };
+      }
+
+      return {
+        ok: true,
+        action: params.action,
+        result: runResult.response.result ?? {},
+        diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
+          durationMs: runResult.durationMs,
+          stderr: runResult.stderr,
+        }),
+      };
+    },
+  };
+}

package/src/mempalace/config.ts

@@ -0,0 +1,75 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import type { PlatformPaths } from "../platform/types.js";
+import type { MempalaceConfig, SupipowersConfig } from "../types.js";
+import { getProjectStateDir } from "../workspace/state-paths.js";
+import { resolveRepoIdentityRootFromFs } from "../workspace/repo-root.js";
+
+export interface ResolvedMempalaceConfig extends MempalaceConfig {
+  managedVenvPath: string;
+  palacePath: string;
+  managedVenvPathDisplay: string;
+  palacePathDisplay: string;
+}
+
+function expandUserPath(input: string, cwd: string): string {
+  const trimmed = input.trim();
+  if (trimmed === "~") {
+    return homedir();
+  }
+
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return path.join(homedir(), trimmed.slice(2));
+  }
+
+  return path.isAbsolute(trimmed) ? path.normalize(trimmed) : path.resolve(cwd, trimmed);
+}
+
+function sanitizedWing(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s/\\]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/[-_]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function normalizeMempalaceWing(value: string): string {
+  return sanitizedWing(value) || "project";
+}
+
+export function resolveMempalaceConfig(
+  config: SupipowersConfig,
+  cwd: string,
+  _paths: PlatformPaths,
+): ResolvedMempalaceConfig {
+  const raw = config.mempalace;
+  return {
+    ...raw,
+    managedVenvPath: expandUserPath(raw.managedVenvPath, cwd),
+    palacePath: expandUserPath(raw.palacePath, cwd),
+    managedVenvPathDisplay: raw.managedVenvPath,
+    palacePathDisplay: raw.palacePath,
+  };
+}
+
+export function resolveDefaultWing(
+  config: Pick<ResolvedMempalaceConfig, "defaultWingStrategy" | "explicitWing">,
+  cwd: string,
+  paths: PlatformPaths,
+): string {
+  if (config.defaultWingStrategy === "explicit") {
+    const explicit = sanitizedWing(config.explicitWing ?? "");
+    if (!explicit) {
+      throw new Error("mempalace.defaultWingStrategy is explicit but explicitWing is empty");
+    }
+    return explicit;
+  }
+
+  if (config.defaultWingStrategy === "project-slug") {
+    return normalizeMempalaceWing(path.basename(getProjectStateDir(paths, cwd)));
+  }
+
+  return normalizeMempalaceWing(path.basename(resolveRepoIdentityRootFromFs(cwd)));
+}

package/src/mempalace/format.ts

@@ -0,0 +1,163 @@
+import type { MempalaceAction } from "./schema.js";
+import type { MempalaceConfig } from "../types.js";
+
+export interface MempalaceFormattedResult {
+  text: string;
+  details: unknown;
+}
+
+export interface MempalaceBridgeError {
+  code: string;
+  message: string;
+  remediation?: string;
+  [key: string]: unknown;
+}
+
+type ResultBudgets = MempalaceConfig["budgets"];
+
+type RecordValue = Record<string, unknown>;
+
+const TRUNCATED_SEARCH_GUIDANCE = "\n\nOutput truncated. Use a narrower query/limit or call get_drawer with a result id for full text.";
+const TRUNCATED_LIST_GUIDANCE = "\n\nOutput truncated. Re-run with a smaller limit or a more specific wing/room.";
+
+function asRecord(value: unknown): RecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as RecordValue : {};
+}
+
+function asArray(value: unknown): RecordValue[] {
+  return Array.isArray(value) ? value.map(asRecord) : [];
+}
+
+function stringValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+
+function truncateText(text: string, maxChars: number, guidance: string): string {
+  if (text.length <= maxChars) return text;
+  if (maxChars <= guidance.length + 1) {
+    return guidance.trim().slice(0, maxChars);
+  }
+  const headChars = maxChars - guidance.length - 1;
+  return `${text.slice(0, headChars).trimEnd()}…${guidance}`;
+}
+
+function formatSimilarity(value: unknown): string {
+  return typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "n/a";
+}
+
+function formatSearch(result: RecordValue, budgets: ResultBudgets): string {
+  const results = asArray(result.results ?? result.items);
+  const query = stringValue(result.query) || "(unspecified query)";
+  const count = typeof result.count === "number" ? result.count : results.length;
+  const lines = [`MemPalace search`, `Search results for ${query} (${count})`];
+
+  for (const [index, item] of results.entries()) {
+    const id = stringValue(item.id ?? item.drawer_id) || `#${index + 1}`;
+    const wing = stringValue(item.wing);
+    const room = stringValue(item.room);
+    const location = [wing, room].filter(Boolean).join("/") || "unscoped";
+    const excerpt = stringValue(item.content ?? item.text ?? item.entry ?? item.summary).replace(/\s+/g, " ").trim();
+    lines.push(`${index + 1}. ${id} · ${location} · similarity ${formatSimilarity(item.similarity ?? item.score)}`);
+    if (excerpt) lines.push(`   ${excerpt}`);
+  }
+
+  return truncateText(lines.join("\n"), budgets.searchResultChars, TRUNCATED_SEARCH_GUIDANCE);
+}
+
+function formatDrawerList(result: RecordValue, budgets: ResultBudgets): string {
+  const drawers = asArray(result.drawers ?? result.results ?? result.items);
+  const lines = [`Drawers (${drawers.length})`];
+
+  for (const drawer of drawers) {
+    const id = stringValue(drawer.id ?? drawer.drawer_id) || "unknown";
+    const location = [stringValue(drawer.wing), stringValue(drawer.room)].filter(Boolean).join("/") || "unscoped";
+    const updated = stringValue(drawer.updated_at ?? drawer.created_at ?? drawer.timestamp);
+    lines.push(`- ${id} · ${location}${updated ? ` · ${updated}` : ""}`);
+  }
+
+  return truncateText(lines.join("\n"), budgets.listResultChars, TRUNCATED_LIST_GUIDANCE);
+}
+
+function formatDiary(result: RecordValue, budgets: ResultBudgets): string {
+  const entries = asArray(result.entries ?? result.results ?? result.items);
+  const lines = [`Diary entries (${entries.length})`];
+
+  for (const entry of entries) {
+    const timestamp = stringValue(entry.timestamp ?? entry.created_at);
+    const agent = stringValue(entry.agent_name ?? entry.agent) || "unknown-agent";
+    const text = stringValue(entry.entry ?? entry.content ?? entry.text).replace(/\s+/g, " ").trim();
+    lines.push(`- ${timestamp ? `${timestamp} · ` : ""}${agent}: ${text}`);
+  }
+
+  return truncateText(lines.join("\n"), budgets.diaryChars, TRUNCATED_LIST_GUIDANCE);
+}
+
+function formatStatus(result: RecordValue): string {
+  const wings = Array.isArray(result.wings) ? result.wings.length : result.wingCount ?? result.wings_count ?? "unknown";
+  const lines = ["MemPalace status"];
+  const palacePath = stringValue(result.palacePath ?? result.palace_path ?? result.palace);
+  if (palacePath) lines.push(`palace: ${palacePath}`);
+  if ("ready" in result) lines.push(`ready: ${String(result.ready)}`);
+  if ("version" in result) lines.push(`version: ${stringValue(result.version)}`);
+  lines.push(`wings: ${String(wings)}`);
+  return lines.join("\n");
+}
+
+function formatGeneric(action: MempalaceAction, result: RecordValue, budgets: ResultBudgets): string {
+  const summary = stringValue(result.message ?? result.summary ?? result.status);
+  if (summary) return truncateText(`MemPalace ${action}: ${summary}`, budgets.listResultChars, TRUNCATED_LIST_GUIDANCE);
+  return truncateText(`MemPalace ${action} result\n${JSON.stringify(result, null, 2)}`, budgets.listResultChars, TRUNCATED_LIST_GUIDANCE);
+}
+
+export function formatMempalaceResult(
+  action: MempalaceAction,
+  result: unknown,
+  budgets: ResultBudgets,
+): MempalaceFormattedResult {
+  const record = asRecord(result);
+  let text: string;
+
+  if (action === "status" || action === "version") {
+    text = formatStatus(record);
+  } else if (action === "search" || action === "wake_up") {
+    text = formatSearch(record, budgets);
+  } else if (action === "list_drawers" || action === "list_wings" || action === "list_rooms") {
+    text = formatDrawerList(record, budgets);
+  } else if (action === "diary_read") {
+    text = formatDiary(record, budgets);
+  } else {
+    text = formatGeneric(action, record, budgets);
+  }
+
+  return { text, details: result };
+}
+
+export function formatMempalaceError(error: MempalaceBridgeError, details: Record<string, unknown> = {}): MempalaceFormattedResult {
+  const lines = [`MemPalace error (${error.code})`, error.message];
+  if (error.remediation) lines.push(`Remediation: ${error.remediation}`);
+
+  // Surface bridge subprocess output. When the bridge fails (e.g. malformed
+  // JSON, non-zero exit) the model and the user need to see what actually
+  // happened, not just the abstract error code.
+  const diagnostics = (details.diagnostics ?? {}) as Record<string, unknown>;
+  const stderrTail = pickString(diagnostics.stderrTail) ?? pickString(details.stderrTail);
+  const stdoutPreview = pickString(diagnostics.stdoutPreview) ?? pickString(details.stdoutPreview);
+  if (stderrTail && stderrTail.trim().length > 0) {
+    lines.push("", "Bridge stderr:", stderrTail.trim());
+  }
+  if (stdoutPreview && stdoutPreview.trim().length > 0) {
+    lines.push("", "Bridge stdout (preview):", stdoutPreview.trim());
+  }
+
+  return {
+    text: lines.join("\n"),
+    details: { ...details, error },
+  };
+}
+
+function pickString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}