gorsee 0.2.4 → 0.2.5

package/dist-pkg/ai/index.js

@@ -0,0 +1,267 @@
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import {
+  resolveAISessionPackConfig,
+  shouldGenerateAISessionPack,
+  writeAISessionPack
+} from "./session-pack.js";
+export {
+  GORSEE_AI_CONTEXT_SCHEMA_VERSION
+} from "./contracts.js";
+export {
+  writeArtifactFailurePack,
+  writeArtifactLifecycleEvent,
+  writeArtifactSuccessPack,
+  runArtifactLifecycleStep
+} from "./artifact-lifecycle.js";
+export {
+  createAIBridgeHandler,
+  createAIBridgeServer
+} from "./bridge.js";
+export {
+  buildAIHealthReport,
+  readAIDiagnosticsSnapshot,
+  readReactiveTraceArtifact,
+  readAIEvents,
+  resolveAIStorePaths
+} from "./store.js";
+export {
+  createAIMCPServer,
+  createLineReader
+} from "./mcp.js";
+export {
+  createAIContextPacket,
+  renderAIContextMarkdown
+} from "./summary.js";
+export {
+  buildAIContextBundle,
+  renderAIContextBundleMarkdown
+} from "./bundle.js";
+export {
+  buildIDEProjection,
+  resolveIDEProjectionPaths,
+  writeIDEProjection
+} from "./ide.js";
+export {
+  createIDEProjectionWatcher
+} from "./watch.js";
+export {
+  resolveAISessionPackConfig,
+  resolveAISessionPackPaths,
+  shouldGenerateAISessionPack,
+  writeAISessionPack
+} from "./session-pack.js";
+const DEFAULT_REDACT_KEYS = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-gorsee-csrf",
+  "token",
+  "secret",
+  "password",
+  "apiKey",
+  "api_key"
+];
+let currentConfig = {
+  enabled: !1
+}, sessionPackTimer;
+export function configureAIObservability(config = {}) {
+  currentConfig = {
+    ...config,
+    enabled: config.enabled ?? !1
+  };
+}
+export function getAIObservabilityConfig() {
+  return currentConfig;
+}
+export function isAIObservabilityEnabled() {
+  return currentConfig.enabled === !0;
+}
+export async function emitAIEvent(input) {
+  if (!isAIObservabilityEnabled())
+    return;
+  const event = {
+    id: input.id ?? crypto.randomUUID(),
+    ts: input.ts ?? new Date().toISOString(),
+    ...input,
+    data: redactValue(input.data, currentConfig.redactKeys ?? DEFAULT_REDACT_KEYS)
+  }, writes = [];
+  if (currentConfig.jsonlPath)
+    writes.push(writeJSONL(currentConfig.jsonlPath, event));
+  if (currentConfig.diagnosticsPath && shouldPersistDiagnostic(event))
+    writes.push(writeDiagnosticsSnapshot(currentConfig.diagnosticsPath, event));
+  if (currentConfig.bridge && shouldForwardEvent(event, currentConfig.bridge))
+    writes.push(postBridgeEvent(currentConfig.bridge, event));
+  await Promise.allSettled(writes);
+  scheduleSessionPack(event);
+}
+export async function emitAIDiagnostic(input) {
+  await emitAIEvent({
+    kind: "diagnostic.issue",
+    severity: input.severity,
+    source: input.source,
+    message: input.message,
+    code: input.code,
+    file: input.file,
+    line: input.line,
+    route: input.route,
+    requestId: input.requestId,
+    traceId: input.traceId,
+    spanId: input.spanId,
+    ts: input.ts,
+    data: input.fix ? { fix: input.fix } : void 0
+  });
+}
+export function createTraceIds(parent) {
+  return {
+    requestId: parent?.requestId ?? crypto.randomUUID(),
+    traceId: parent?.traceId ?? crypto.randomUUID(),
+    spanId: crypto.randomUUID(),
+    parentSpanId: parent?.spanId
+  };
+}
+export async function runWithAITrace(input, fn) {
+  const trace = createTraceIds(input.trace), startedAt = performance.now();
+  await emitAIEvent({
+    ...input,
+    kind: `${input.kind}.start`,
+    requestId: trace.requestId,
+    traceId: trace.traceId,
+    spanId: trace.spanId,
+    parentSpanId: trace.parentSpanId
+  });
+  try {
+    const result = await fn(trace);
+    await emitAIEvent({
+      ...input,
+      kind: `${input.kind}.finish`,
+      requestId: trace.requestId,
+      traceId: trace.traceId,
+      spanId: trace.spanId,
+      parentSpanId: trace.parentSpanId,
+      durationMs: Number((performance.now() - startedAt).toFixed(2))
+    });
+    return result;
+  } catch (error) {
+    await emitAIEvent({
+      ...input,
+      kind: `${input.kind}.error`,
+      severity: "error",
+      requestId: trace.requestId,
+      traceId: trace.traceId,
+      spanId: trace.spanId,
+      parentSpanId: trace.parentSpanId,
+      durationMs: Number((performance.now() - startedAt).toFixed(2)),
+      data: {
+        ...input.data ?? {},
+        error: error instanceof Error ? { name: error.name, message: error.message } : String(error)
+      }
+    });
+    throw error;
+  }
+}
+export function resolveAIObservabilityConfig(cwd, config) {
+  const enabled = config?.enabled ?? !1, resolvedJsonlPath = config?.jsonlPath ? resolvePath(cwd, config.jsonlPath) : join(cwd, ".gorsee", "ai-events.jsonl"), resolvedDiagnosticsPath = config?.diagnosticsPath ? resolvePath(cwd, config.diagnosticsPath) : join(cwd, ".gorsee", "ai-diagnostics.json");
+  return {
+    ...config,
+    enabled,
+    jsonlPath: enabled ? resolvedJsonlPath : config?.jsonlPath,
+    diagnosticsPath: enabled ? resolvedDiagnosticsPath : config?.diagnosticsPath,
+    sessionPack: enabled ? resolveAISessionPackConfig(cwd, config?.sessionPack) : config?.sessionPack
+  };
+}
+export function __resetAIObservability() {
+  currentConfig = { enabled: !1 };
+  if (sessionPackTimer)
+    clearTimeout(sessionPackTimer);
+  sessionPackTimer = void 0;
+}
+function shouldForwardEvent(event, bridge) {
+  if (!bridge.events || bridge.events.length === 0)
+    return !0;
+  return bridge.events.includes(event.kind);
+}
+async function writeJSONL(path, event) {
+  await mkdir(dirname(path), { recursive: !0 });
+  await appendFile(path, `${JSON.stringify(event)}
+`, "utf-8");
+}
+async function writeDiagnosticsSnapshot(path, event) {
+  const snapshot = {
+    updatedAt: event.ts,
+    sessionId: currentConfig.sessionId,
+    latest: {
+      code: event.code,
+      message: event.message,
+      severity: event.severity,
+      source: event.source,
+      file: event.file,
+      line: event.line,
+      route: event.route,
+      requestId: event.requestId,
+      traceId: event.traceId,
+      spanId: event.spanId
+    }
+  };
+  await mkdir(dirname(path), { recursive: !0 });
+  await writeFile(path, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+async function postBridgeEvent(bridge, event) {
+  const controller = new AbortController, timeout = setTimeout(() => controller.abort(), bridge.timeoutMs ?? 300);
+  try {
+    await fetch(bridge.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...bridge.headers ?? {}
+      },
+      body: JSON.stringify(event),
+      signal: controller.signal
+    });
+  } catch {} finally {
+    clearTimeout(timeout);
+  }
+}
+function redactValue(value, redactKeys) {
+  if (value == null)
+    return value;
+  if (typeof value === "string")
+    return value.length > 2000 ? `${value.slice(0, 2000)}...[truncated]` : value;
+  if (Array.isArray(value))
+    return value.map((item) => redactValue(item, redactKeys));
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      const shouldRedact = redactKeys.some((candidate) => candidate.toLowerCase() === key.toLowerCase());
+      result[key] = shouldRedact ? "[redacted]" : redactValue(nestedValue, redactKeys);
+    }
+    return result;
+  }
+  return value;
+}
+function shouldPersistDiagnostic(event) {
+  return event.kind === "diagnostic.issue" || event.severity === "error" || event.code?.startsWith("E") === !0;
+}
+function resolvePath(cwd, path) {
+  return isAbsolute(path) ? path : join(cwd, path);
+}
+function scheduleSessionPack(event) {
+  const config = currentConfig.sessionPack;
+  if (!currentConfig.enabled || !config)
+    return;
+  if (!shouldGenerateAISessionPack(event, config))
+    return;
+  if (!currentConfig.jsonlPath || !currentConfig.diagnosticsPath)
+    return;
+  const cwd = dirname(dirname(currentConfig.jsonlPath));
+  if (sessionPackTimer)
+    clearTimeout(sessionPackTimer);
+  sessionPackTimer = setTimeout(() => {
+    sessionPackTimer = void 0;
+    writeAISessionPack(cwd, {
+      eventsPath: currentConfig.jsonlPath,
+      diagnosticsPath: currentConfig.diagnosticsPath,
+      reactiveTracePath: join(cwd, ".gorsee", "reactive-trace.json")
+    }, config).catch(() => {});
+  }, config.debounceMs ?? 250);
+}

package/dist-pkg/ai/json.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_AI_JSON_BYTES: number;
+export declare const MAX_AI_EVENTS_READ = 5000;
+export declare function safeJSONParse<T>(raw: string, options?: {
+    maxBytes?: number;
+}): T | null;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist-pkg/ai/json.js

@@ -0,0 +1,14 @@
+export const MAX_AI_JSON_BYTES = 65536, MAX_AI_EVENTS_READ = 5000;
+export function safeJSONParse(raw, options = {}) {
+  const maxBytes = options.maxBytes ?? MAX_AI_JSON_BYTES;
+  if (Buffer.byteLength(raw, "utf-8") > maxBytes)
+    return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist-pkg/ai/mcp.d.ts

@@ -0,0 +1,28 @@
+import type { AIStorePaths } from "./store.js";
+interface JSONRPCRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: any;
+}
+interface JSONRPCResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface AIMCPServerOptions {
+    paths: AIStorePaths;
+    limit?: number;
+}
+export declare function createAIMCPServer(options: AIMCPServerOptions): {
+    handleRequest: (request: JSONRPCRequest) => Promise<JSONRPCResponse | null>;
+    serve: (input: AsyncIterable<string>, output: {
+        write(chunk: string): void;
+    }) => Promise<void>;
+};
+export declare function createLineReader(input: NodeJS.ReadStream): AsyncIterable<string>;
+export {};

package/dist-pkg/ai/mcp.js

@@ -0,0 +1,152 @@
+import { buildAIHealthReport, readAIDiagnosticsSnapshot, readAIEvents } from "./store.js";
+import { MAX_AI_JSON_BYTES, safeJSONParse } from "./json.js";
+export function createAIMCPServer(options) {
+  async function handleRequest(request) {
+    switch (request.method) {
+      case "initialize":
+        return ok(request.id, {
+          protocolVersion: "2025-06-18",
+          serverInfo: { name: "gorsee-ai-mcp", version: "0.1.0" },
+          capabilities: {
+            tools: {}
+          }
+        });
+      case "notifications/initialized":
+        return null;
+      case "tools/list":
+        return ok(request.id, {
+          tools: [
+            {
+              name: "gorsee_ai_recent_events",
+              description: "Read the most recent structured AI/runtime/build/check events.",
+              inputSchema: {
+                type: "object",
+                properties: {
+                  limit: { type: "number" }
+                }
+              }
+            },
+            {
+              name: "gorsee_ai_diagnostics",
+              description: "Read the latest AI diagnostics snapshot.",
+              inputSchema: { type: "object", properties: {} }
+            },
+            {
+              name: "gorsee_ai_doctor",
+              description: "Summarize current AI health, incidents, and diagnostics for the workspace.",
+              inputSchema: {
+                type: "object",
+                properties: {
+                  limit: { type: "number" }
+                }
+              }
+            }
+          ]
+        });
+      case "tools/call":
+        return ok(request.id, await callTool(request.params));
+      default:
+        return err(request.id, -32601, `Method not found: ${request.method}`);
+    }
+  }
+  async function serve(input, output) {
+    for await (const line of input) {
+      const trimmed = line.trim();
+      if (!trimmed)
+        continue;
+      let request;
+      request = safeJSONParse(trimmed, { maxBytes: MAX_AI_JSON_BYTES });
+      if (!request) {
+        output.write(`${JSON.stringify(err(null, -32700, "Parse error"))}
+`);
+        continue;
+      }
+      const response = await handleRequest(request);
+      if (response)
+        output.write(`${JSON.stringify(response)}
+`);
+    }
+  }
+  return {
+    handleRequest,
+    serve
+  };
+  async function callTool(params) {
+    const name = params?.name, args = params?.arguments, limit = Math.max(1, Math.min(args?.limit ?? options.limit ?? 50, 500));
+    if (name === "gorsee_ai_recent_events") {
+      const events = await readAIEvents(options.paths.eventsPath, { limit });
+      return text(JSON.stringify(events, null, 2));
+    }
+    if (name === "gorsee_ai_diagnostics") {
+      const snapshot = await readAIDiagnosticsSnapshot(options.paths.diagnosticsPath);
+      return text(JSON.stringify(snapshot ?? {}, null, 2));
+    }
+    if (name === "gorsee_ai_doctor") {
+      const report = await buildAIHealthReport(options.paths, { limit });
+      return text(renderDoctorText(report));
+    }
+    throw Error(`Unknown tool: ${name}`);
+  }
+}
+export function createLineReader(input) {
+  const decoder = new TextDecoder;
+  return {
+    async* [Symbol.asyncIterator]() {
+      let buffer = "";
+      for await (const chunk of input) {
+        buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: !0 });
+        while (buffer.includes(`
+`)) {
+          const index = buffer.indexOf(`
+`), line = buffer.slice(0, index);
+          buffer = buffer.slice(index + 1);
+          yield line;
+        }
+      }
+      if (buffer.length > 0)
+        yield buffer;
+    }
+  };
+}
+function renderDoctorText(report) {
+  const lines = [
+    `Events: ${report.events.total}`,
+    `Diagnostics: ${report.diagnostics.total}`,
+    `Errors: ${report.diagnostics.errors}`,
+    `Warnings: ${report.diagnostics.warnings}`
+  ];
+  if (report.events.latest)
+    lines.push(`Latest event: ${report.events.latest.kind} at ${report.events.latest.ts}`);
+  if (report.diagnostics.latest?.code)
+    lines.push(`Latest diagnostic: ${report.diagnostics.latest.code} ${report.diagnostics.latest.message ?? ""}`.trim());
+  if (report.incidents.length > 0) {
+    lines.push("Incidents:");
+    for (const incident of report.incidents.slice(0, 5))
+      lines.push(`- [${incident.kind}] ${incident.message}`);
+  }
+  if (report.incidentClusters.length > 0) {
+    lines.push("Incident clusters:");
+    for (const cluster of report.incidentClusters.slice(0, 5)) {
+      const loc = cluster.file ? ` (${cluster.file})` : cluster.route ? ` (${cluster.route})` : "";
+      lines.push(`- [${cluster.kind}] x${cluster.count}${loc}`);
+    }
+  }
+  if (report.artifactRegressions.length > 0) {
+    lines.push("Artifact regressions:");
+    for (const artifact of report.artifactRegressions.slice(0, 5)) {
+      const details = [artifact.version, artifact.path].filter(Boolean).join(" ");
+      lines.push(`- [${artifact.phase}] errors=${artifact.errors} warnings=${artifact.warnings} successes=${artifact.successes}${details ? ` (${details})` : ""}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function text(value) {
+  return { content: [{ type: "text", text: value }] };
+}
+function ok(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function err(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}

package/dist-pkg/ai/session-pack.d.ts

@@ -0,0 +1,28 @@
+import type { AIStorePaths } from "./store.js";
+import { type AIContextBundle } from "./bundle.js";
+export interface AISessionPackConfig {
+    enabled?: boolean;
+    outDir?: string;
+    triggerKinds?: string[];
+    debounceMs?: number;
+    limit?: number;
+    maxSnippets?: number;
+    formats?: Array<"json" | "markdown">;
+}
+export interface AISessionPackPaths {
+    outDir: string;
+    latestJsonPath: string;
+    latestMarkdownPath: string;
+    historyDir: string;
+}
+export declare function resolveAISessionPackConfig(cwd: string, config?: AISessionPackConfig): AISessionPackConfig | undefined;
+export declare function resolveAISessionPackPaths(cwd: string, config?: AISessionPackConfig): AISessionPackPaths;
+export declare function writeAISessionPack(cwd: string, storePaths: AIStorePaths, config?: AISessionPackConfig): Promise<{
+    bundle: AIContextBundle;
+    paths: AISessionPackPaths;
+    stamp: string;
+}>;
+export declare function shouldGenerateAISessionPack(event: {
+    kind: string;
+    severity: string;
+}, config?: AISessionPackConfig): boolean;

package/dist-pkg/ai/session-pack.js

@@ -0,0 +1,57 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { buildAIContextBundle, renderAIContextBundleMarkdown } from "./bundle.js";
+import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
+export function resolveAISessionPackConfig(cwd, config) {
+  if (!config?.enabled)
+    return config;
+  return {
+    enabled: !0,
+    outDir: config.outDir ? isAbsolute(config.outDir) ? config.outDir : join(cwd, config.outDir) : join(cwd, ".gorsee", "agent"),
+    triggerKinds: config.triggerKinds ?? ["diagnostic.issue", "request.error", "build.summary", "check.summary"],
+    debounceMs: config.debounceMs ?? 250,
+    limit: config.limit ?? 200,
+    maxSnippets: config.maxSnippets ?? 6,
+    formats: config.formats ?? ["json", "markdown"]
+  };
+}
+export function resolveAISessionPackPaths(cwd, config) {
+  const outDir = config?.outDir ? isAbsolute(config.outDir) ? config.outDir : join(cwd, config.outDir) : join(cwd, ".gorsee", "agent");
+  return {
+    outDir,
+    latestJsonPath: join(outDir, "latest.json"),
+    latestMarkdownPath: join(outDir, "latest.md"),
+    historyDir: join(outDir, "history")
+  };
+}
+export async function writeAISessionPack(cwd, storePaths, config) {
+  const resolved = resolveAISessionPackConfig(cwd, { enabled: !0, ...config ?? {} }), paths = resolveAISessionPackPaths(cwd, resolved), bundle = await buildAIContextBundle(cwd, storePaths, {
+    limit: resolved.limit,
+    maxSnippets: resolved.maxSnippets
+  });
+  await mkdir(paths.historyDir, { recursive: !0 });
+  const stamp = bundle.generatedAt.replace(/[:.]/g, "-"), json = JSON.stringify(bundle, null, 2), markdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    renderAIContextBundleMarkdown(bundle)
+  ].join(`
+`);
+  if ((resolved.formats ?? ["json", "markdown"]).includes("json")) {
+    await writeFile(paths.latestJsonPath, json, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.json`), json, "utf-8");
+  }
+  if ((resolved.formats ?? ["json", "markdown"]).includes("markdown")) {
+    await writeFile(paths.latestMarkdownPath, markdown, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.md`), markdown, "utf-8");
+  }
+  return { bundle, paths, stamp };
+}
+export function shouldGenerateAISessionPack(event, config) {
+  if (!config?.enabled)
+    return !1;
+  if ((config.triggerKinds ?? []).includes(event.kind)) {
+    if (event.kind.endsWith(".summary"))
+      return event.severity === "error" || event.severity === "warn";
+    return !0;
+  }
+  return event.severity === "error";
+}

package/dist-pkg/ai/store.d.ts

@@ -0,0 +1,67 @@
+import type { AIDiagnostic, AIEvent } from "./index.js";
+import type { ReactiveTraceArtifact } from "../reactive/diagnostics.js";
+export interface AIStorePaths {
+    eventsPath: string;
+    diagnosticsPath: string;
+    reactiveTracePath: string;
+}
+export interface AIHealthReport {
+    events: {
+        total: number;
+        bySeverity: Record<string, number>;
+        byKind: Record<string, number>;
+        latest?: AIEvent;
+    };
+    diagnostics: {
+        total: number;
+        latest?: AIDiagnostic;
+        errors: number;
+        warnings: number;
+    };
+    incidents: Array<{
+        kind: string;
+        message: string;
+        ts: string;
+        route?: string;
+        file?: string;
+        line?: number;
+        code?: string;
+    }>;
+    incidentClusters: Array<{
+        key: string;
+        count: number;
+        kind: string;
+        latestTs: string;
+        route?: string;
+        file?: string;
+        requestId?: string;
+        traceId?: string;
+        messages: string[];
+        codes: string[];
+    }>;
+    artifactRegressions: Array<{
+        key: string;
+        phase: string;
+        path?: string;
+        version?: string;
+        errors: number;
+        warnings: number;
+        successes: number;
+        latestTs: string;
+        latestStatus: "error" | "warn" | "success" | "info";
+        messages: string[];
+    }>;
+}
+export declare function resolveAIStorePaths(cwd: string): AIStorePaths;
+export declare function readAIEvents(path: string, options?: {
+    limit?: number;
+}): Promise<AIEvent[]>;
+export declare function readAIDiagnosticsSnapshot(path: string): Promise<{
+    updatedAt?: string;
+    sessionId?: string;
+    latest?: Partial<AIDiagnostic>;
+} | null>;
+export declare function readReactiveTraceArtifact(path: string): Promise<ReactiveTraceArtifact | null>;
+export declare function buildAIHealthReport(paths: AIStorePaths, options?: {
+    limit?: number;
+}): Promise<AIHealthReport>;