septum 0.1.0

package/src/core/telemetry/telemetry.ts

@@ -0,0 +1,86 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface SeptumToolCallEvent {
+  timestamp?: string;
+  event: "tool_call_completed" | "tool_call_failed";
+  tool: string;
+  duration_ms: number;
+  input: Record<string, any>;
+  metrics?: {
+    bytes_out?: number;
+    lines_out?: number;
+    nodes_returned?: number;
+  };
+  session?: {
+    feature_key?: string | null;
+    domain?: string | null;
+  } | null;
+  status: "success" | "error";
+  error?: {
+    code?: string;
+    message: string;
+    stack?: string;
+  };
+}
+
+export class SeptumTelemetry {
+  private static readonly MAX_LOG_SIZE_BYTES = 2 * 1024 * 1024; // 2MB
+  private static readonly SLOW_EXECUTION_THRESHOLD_MS = 250;
+
+  /**
+   * Resolves the log file path inside the active workspace's .septum directory.
+   */
+  public static getLogPath(workspaceRoot: string = process.cwd()): string {
+    return join(workspaceRoot, ".septum", "septum.log");
+  }
+
+  /**
+   * Records a tool call event to both stderr (dual-sink) and .septum/septum.log.
+   */
+  public static recordToolCall(
+    event: SeptumToolCallEvent,
+    workspaceRoot: string = process.cwd()
+  ): void {
+    const payload: SeptumToolCallEvent = {
+      timestamp: event.timestamp || new Date().toISOString(),
+      ...event,
+    };
+
+    const jsonLine = JSON.stringify(payload);
+
+    // Sink 1: Live stderr stream for operator monitoring (slow queries & failures)
+    if (payload.status === "error") {
+      console.error(`[Septum Telemetry ERROR] ${jsonLine}`);
+    } else if (payload.duration_ms >= this.SLOW_EXECUTION_THRESHOLD_MS) {
+      console.error(`[Septum Telemetry SLOW_WARN] ${jsonLine}`);
+    }
+
+    // Sink 2: Append-only persistent file recorder in .septum/septum.log
+    try {
+      const logPath = this.getLogPath(workspaceRoot);
+      const logDir = dirname(logPath);
+
+      if (!existsSync(logDir)) {
+        mkdirSync(logDir, { recursive: true });
+      }
+
+      // Check for rotation if file exceeds 2MB
+      if (existsSync(logPath)) {
+        try {
+          const stats = statSync(logPath);
+          if (stats.size >= this.MAX_LOG_SIZE_BYTES) {
+            const rotatedPath = `${logPath}.1`;
+            renameSync(logPath, rotatedPath);
+          }
+        } catch {
+          // If stat/rotation fails, proceed to append without crashing
+        }
+      }
+
+      appendFileSync(logPath, `${jsonLine}\n`, "utf8");
+    } catch {
+      // Telemetry file writes must never crash the main application process
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from "./types/index.ts";
+export * from "./core/config/schema.ts";
+export * from "./core/config/loader.ts";
+export * from "./core/database/client.ts";
+export * from "./core/database/repository.ts";
+export * from "./core/parser/extractors/base.ts";
+export * from "./core/parser/tree-sitter.ts";
+export * from "./core/ingestion/pipeline.ts";
+export * from "./core/boundary/evaluator.ts";
+export * from "./core/resolver/call-graph-tracer.ts";
+export * from "./core/resolver/vertical-slice-tracer.ts";
+export * from "./mcp/server.ts";
+export * from "./cli/index.ts";
+
+import { runCLI } from "./cli/index.ts";
+if (import.meta.main) {
+  runCLI(process.argv);
+}

package/src/mcp/schemas.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+export const GetDomainCatalogSchema = z.object({
+  domain: z.string().optional(),
+  archetype: z.string().optional(),
+});
+export type GetDomainCatalogArgs = z.infer<typeof GetDomainCatalogSchema>;
+
+export const GetFeatureContextSchema = z.object({
+  feature: z.string().min(1, "feature is required"),
+});
+export type GetFeatureContextArgs = z.infer<typeof GetFeatureContextSchema>;
+
+export const LocateSymbolSchema = z.object({
+  query: z.string().min(1, "query is required"),
+  domain: z.string().optional(),
+  limit: z.number().int().positive().optional().default(10),
+});
+export type LocateSymbolArgs = z.infer<typeof LocateSymbolSchema>;
+
+export const GetSymbolSchema = z.object({
+  symbol: z.string().min(1, "symbol is required"),
+  domain: z.string().optional(),
+  include_dependencies: z.boolean().optional().default(true),
+});
+export type GetSymbolArgs = z.infer<typeof GetSymbolSchema>;
+
+export const GetSymbolImpactSchema = z.object({
+  symbol: z.string().min(1, "symbol is required"),
+});
+export type GetSymbolImpactArgs = z.infer<typeof GetSymbolImpactSchema>;
+
+export const TraceVerticalSliceSchema = z.object({
+  query: z.string().min(1, "query is required"),
+  max_depth: z.number().int().positive().optional().default(5),
+});
+export type TraceVerticalSliceArgs = z.infer<typeof TraceVerticalSliceSchema>;
+
+export const CheckBoundarySchema = z.object({
+  file_path: z.string().optional(),
+  file_paths: z.array(z.string()).optional(),
+  proposed_imports: z.array(z.string()).default([]),
+  feature_key: z.string().optional(),
+});
+export type CheckBoundaryArgs = z.infer<typeof CheckBoundarySchema>;
+
+export const GetSymbolHotspotsSchema = z.object({
+  domain: z.string().optional(),
+  limit: z.number().int().positive().optional().default(10),
+});
+export type GetSymbolHotspotsArgs = z.infer<typeof GetSymbolHotspotsSchema>;
+
+export const RegisterDomainSchema = z.object({
+  name: z.string().min(1, "Domain name is required"),
+  root: z.string().min(1, "Domain root path is required"),
+  description: z.string().optional(),
+  allowed_dependencies: z.array(z.string()).optional(),
+  forbidden_dependencies: z.array(z.string()).optional(),
+  archetypes: z.record(z.string()).optional(),
+  ingest_now: z.boolean().optional().default(false),
+});
+export type RegisterDomainArgs = z.infer<typeof RegisterDomainSchema>;
+
+export const AutoDiscoverDomainsSchema = z.object({
+  persist: z.boolean().optional().default(true),
+});
+export type AutoDiscoverDomainsArgs = z.infer<typeof AutoDiscoverDomainsSchema>;
+