septum 0.1.1 → 0.1.3

package/src/mcp/server.ts

@@ -54,12 +54,51 @@ import {
   TraceVerticalSliceSchema,
 } from "./schemas.ts";
 import { SEPTUM_VERSION } from "../version.ts";
+import { resolveWorkspaceRoot } from "../core/resolver/path-resolver.ts";
+import type { ValidatedSeptumConfig } from "../core/config/schema.ts";
 
-export async function runMCPServer(): Promise<void> {
-  const config = ConfigLoader.load();
+interface WorkspaceContext {
+  root: string;
+  config: ValidatedSeptumConfig;
+  db: SeptumDatabase;
+  repo: SeptumRepository;
+  evaluator: BoundaryEvaluator;
+  pipeline: IngestionPipeline;
+}
+
+const workspaceContextCache = new Map<string, WorkspaceContext>();
+
+function extractPathHint(args: Record<string, any> | undefined): string | undefined {
+  if (!args) return undefined;
+  if (typeof args.workspace_path === "string" && args.workspace_path) return args.workspace_path;
+  if (typeof args.target_path === "string" && args.target_path) return args.target_path;
+  if (typeof args.project_root === "string" && args.project_root) return args.project_root;
+  if (typeof args.file_path === "string" && args.file_path) return args.file_path;
+  if (Array.isArray(args.file_paths) && args.file_paths[0]) return args.file_paths[0];
+  if (typeof args.root === "string" && args.root) return args.root;
+  return undefined;
+}
+
+function getWorkspaceContext(pathHint?: string): WorkspaceContext {
+  const root = resolveWorkspaceRoot(pathHint);
+  let ctx = workspaceContextCache.get(root);
+  if (ctx) {
+    return ctx;
+  }
+
+  const config = ConfigLoader.load(undefined, root);
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
   const evaluator = new BoundaryEvaluator(repo);
+  const pipeline = new IngestionPipeline(repo, root);
+
+  ctx = { root, config, db, repo, evaluator, pipeline };
+  workspaceContextCache.set(root, ctx);
+  return ctx;
+}
+
+export async function runMCPServer(): Promise<void> {
+  const initialCtx = getWorkspaceContext();
 
   const server = new Server(
     {
@@ -297,7 +336,10 @@ export async function runMCPServer(): Promise<void> {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const startTime = performance.now();
-    const activeSession = SessionManager.getActiveSession(process.cwd());
+    const pathHint = extractPathHint(args as Record<string, any>);
+    const ctx = getWorkspaceContext(pathHint);
+
+    const activeSession = SessionManager.getActiveSession(ctx.root);
     const sessionPayload = activeSession
       ? { feature_key: activeSession.feature_key, domain: activeSession.domain }
       : null;
@@ -316,7 +358,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetDomainCatalog(repo, config, parsed.data);
+        return handleGetDomainCatalog(ctx.repo, ctx.config, parsed.data, ctx.root);
       } else if (name === "septum_get_feature_context") {
         const parsed = GetFeatureContextSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -330,7 +372,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetFeatureContext(repo, config, parsed.data);
+        return handleGetFeatureContext(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_locate_symbol") {
         const parsed = LocateSymbolSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -344,7 +386,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleLocateSymbol(repo, config, parsed.data);
+        return await handleLocateSymbol(ctx.repo, ctx.config, parsed.data, ctx.pipeline, ctx.root);
       } else if (name === "septum_get_symbol") {
         const parsed = GetSymbolSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -358,7 +400,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbol(repo, config, parsed.data);
+        return handleGetSymbol(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_get_symbol_impact") {
         const parsed = GetSymbolImpactSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -372,7 +414,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbolImpact(repo, config, parsed.data);
+        return handleGetSymbolImpact(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_trace_vertical_slice") {
         const parsed = TraceVerticalSliceSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -386,7 +428,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleTraceVerticalSlice(repo, config, parsed.data);
+        return handleTraceVerticalSlice(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_clear_feature_context") {
         const cleared = handleClearFeatureContext();
         return {
@@ -412,7 +454,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleCheckBoundary(evaluator, config, parsed.data);
+        return handleCheckBoundary(ctx.evaluator, ctx.config, parsed.data, ctx.repo);
       } else if (name === "septum_get_symbol_hotspots") {
         const parsed = GetSymbolHotspotsSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -426,7 +468,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbolHotspots(repo, config, parsed.data);
+        return handleGetSymbolHotspots(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_register_domain") {
         const parsed = RegisterDomainSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -440,7 +482,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return await handleRegisterDomain(repo, config, parsed.data);
+        return await handleRegisterDomain(ctx.repo, ctx.config, parsed.data);
       } else {
         throw new Error(`Unknown tool: '${name}'`);
       }
@@ -522,7 +564,7 @@ export async function runMCPServer(): Promise<void> {
   ]);
 
   try {
-    const bgPipeline = new IngestionPipeline(repo);
+    const bgPipeline = initialCtx.pipeline;
     const cwd = process.cwd();
 
     fsWatcher = watch(cwd, { recursive: true }, (_event, filename) => {
@@ -569,13 +611,14 @@ export async function runMCPServer(): Promise<void> {
         // Ignore watcher close errors during shutdown
       }
     }
-    try {
-      db.close();
-      console.error("[Septum MCP] Database connection closed cleanly.");
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[Septum MCP] Error closing database during cleanup: ${msg}`);
+    for (const ctx of workspaceContextCache.values()) {
+      try {
+        ctx.db.close();
+      } catch (err) {
+        // Ignore close error during shutdown
+      }
     }
+    console.error("[Septum MCP] All database connections closed cleanly.");
     process.exit(0);
   };
 
@@ -590,11 +633,12 @@ export async function runMCPServer(): Promise<void> {
         // Ignore watcher close errors
       }
     }
-    try {
-      db.close();
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[Septum MCP] Error closing database on beforeExit: ${msg}`);
+    for (const ctx of workspaceContextCache.values()) {
+      try {
+        ctx.db.close();
+      } catch {
+        // Ignore close error
+      }
     }
   });
 

package/src/mcp/tools/check-boundary.ts

@@ -1,23 +1,44 @@
 import type { BoundaryEvaluator } from "../../core/boundary/evaluator.ts";
 import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
 
 export interface CheckBoundaryArgs {
   file_path?: string;
+  filePath?: string;
+  file?: string;
+  path?: string;
   file_paths?: string[];
+  filePaths?: string[];
+  files?: string[];
+  paths?: string[];
   proposed_imports?: string[];
+  proposedImports?: string[];
+  imports?: string[];
   feature_key?: string;
+  featureKey?: string;
+  feature?: string;
 }
 
 export function handleCheckBoundary(
   evaluator: BoundaryEvaluator,
   config: ValidatedSeptumConfig,
-  args: CheckBoundaryArgs
+  args: CheckBoundaryArgs,
+  repo?: SeptumRepository
 ) {
+  const rawFilePaths = args.file_paths ?? args.filePaths ?? args.files ?? args.paths;
+  const rawFilePath = args.file_path ?? args.filePath ?? args.file ?? args.path;
+  const proposedImports = args.proposed_imports ?? args.proposedImports ?? args.imports ?? [];
+  const featureKey = args.feature_key ?? args.featureKey ?? args.feature;
+
   const filesToCheck: string[] = [];
-  if (args.file_paths && Array.isArray(args.file_paths) && args.file_paths.length > 0) {
-    filesToCheck.push(...args.file_paths);
-  } else if (args.file_path) {
-    filesToCheck.push(args.file_path);
+  if (rawFilePaths && Array.isArray(rawFilePaths) && rawFilePaths.length > 0) {
+    filesToCheck.push(...rawFilePaths);
+  } else if (rawFilePath) {
+    if (Array.isArray(rawFilePath)) {
+      filesToCheck.push(...rawFilePath);
+    } else {
+      filesToCheck.push(rawFilePath);
+    }
   } else {
     throw new Error("Missing required argument: specify either 'file_path' or 'file_paths'");
   }
@@ -25,11 +46,20 @@ export function handleCheckBoundary(
   // Multi-file batch evaluation
   if (filesToCheck.length > 1) {
     const results = filesToCheck.map((filePath) => {
-      const violations = evaluator.evaluate(filePath, args.proposed_imports ?? [], args.feature_key, config);
+      const violations = evaluator.evaluate(filePath, proposedImports, featureKey, config);
+      const impact = repo?.getFileInboundImpact(filePath);
       return {
         file: filePath,
         status: violations.length > 0 ? "rejected" : "approved",
         violations,
+        impact_summary: impact
+          ? {
+              direct_dependents: impact.direct_dependents_count,
+              top_consumers: impact.top_consumers,
+              symbols_count: impact.symbols_count,
+              risk_level: impact.risk_level,
+            }
+          : undefined,
       };
     });
 
@@ -60,7 +90,8 @@ export function handleCheckBoundary(
 
   // Single file evaluation (backward-compatible output)
   const singleFile = filesToCheck[0];
-  const violations = evaluator.evaluate(singleFile, args.proposed_imports ?? [], args.feature_key, config);
+  const violations = evaluator.evaluate(singleFile, proposedImports, featureKey, config);
+  const impact = repo?.getFileInboundImpact(singleFile);
 
   if (violations.length > 0) {
     return {
@@ -73,6 +104,14 @@ export function handleCheckBoundary(
               file: singleFile,
               violations_count: violations.length,
               violations,
+              impact_summary: impact
+                ? {
+                    direct_dependents: impact.direct_dependents_count,
+                    top_consumers: impact.top_consumers,
+                    symbols_count: impact.symbols_count,
+                    risk_level: impact.risk_level,
+                  }
+                : undefined,
               message: "Boundary violation detected. Proposed imports violate bounded context architecture.",
             },
             null,
@@ -91,7 +130,18 @@ export function handleCheckBoundary(
           {
             status: "approved",
             file: singleFile,
-            message: "No boundary violations detected. Proposed imports are permissible.",
+            impact_summary: impact
+              ? {
+                  direct_dependents: impact.direct_dependents_count,
+                  top_consumers: impact.top_consumers,
+                  symbols_count: impact.symbols_count,
+                  risk_level: impact.risk_level,
+                }
+              : undefined,
+            message:
+              impact && impact.direct_dependents_count > 0
+                ? `No boundary violations detected. Caution: ${impact.direct_dependents_count} dependent file(s) consume this file.`
+                : "No boundary violations detected. Proposed imports are permissible.",
           },
           null,
           2

package/src/mcp/tools/get-domain-catalog.ts

@@ -6,15 +6,45 @@ import type { SeptumRepository } from "../../core/database/repository.ts";
 export interface GetDomainCatalogArgs {
   domain?: string;
   archetype_filter?: string;
+  workspace_path?: string;
 }
 
 export function handleGetDomainCatalog(
   repo: SeptumRepository,
   config: ValidatedSeptumConfig,
-  args: GetDomainCatalogArgs
+  args: GetDomainCatalogArgs,
+  workspaceRoot?: string
 ) {
   if (!args.domain) {
     const allDomains = repo.getAllDomains();
+    if (allDomains.length === 0) {
+      const root = workspaceRoot || process.cwd();
+      const diagnostic = {
+        status: "NOT_INDEXED",
+        total_domains: 0,
+        message: `Workspace '${root}' belum memiliki domain terdaftar dalam Septum catalog.`,
+        suggested_action: {
+          tool: "septum_register_domain",
+          params: {
+            name: "core",
+            root: "src",
+            ingest_now: true,
+          },
+        },
+        agent_guidance:
+          "Panggil tool 'septum_register_domain(name: \"core\", root: \"src\", ingest_now: true)' untuk mendaftarkan dan mengindeks domain utama secara otomatis, atau jalankan 'septum init' di terminal workspace.",
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(diagnostic, null, 2),
+          },
+        ],
+        metadata: diagnostic,
+      };
+    }
+
     const projectType = repo.getMeta("project_type") || "generic";
     const framework = repo.getMeta("framework") || "unknown";
     const archStyle = repo.getMeta("architecture_style") || "modular";

package/src/mcp/tools/locate-symbol.ts

@@ -1,5 +1,8 @@
+import { existsSync, readdirSync } from "node:fs";
+import { isAbsolute, join, basename } from "node:path";
 import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
 import type { SeptumRepository } from "../../core/database/repository.ts";
+import type { IngestionPipeline } from "../../core/ingestion/pipeline.ts";
 import {
   SymbolLocator,
   type SymbolLocationResult,
@@ -8,12 +11,15 @@ import {
 export interface LocateSymbolArgs {
   query: string;
   domain?: string;
+  workspace_path?: string;
 }
 
-export function handleLocateSymbol(
+export async function handleLocateSymbol(
   repo: SeptumRepository,
   config: ValidatedSeptumConfig,
-  args: LocateSymbolArgs
+  args: LocateSymbolArgs,
+  pipeline?: IngestionPipeline,
+  workspaceRoot?: string
 ) {
   if (!args.query) {
     throw new Error(
@@ -21,8 +27,79 @@ export function handleLocateSymbol(
     );
   }
 
+  const root = workspaceRoot || process.cwd();
+
+  // 1. Guarded Lazy Ingestion on Empty Catalog / Cold Start
+  if (repo.countFiles() === 0 && pipeline) {
+    try {
+      await pipeline.run(config);
+    } catch {
+      // Ingestion fallback
+    }
+
+    if (repo.countFiles() === 0) {
+      const diagnostic = {
+        status: "NOT_INDEXED",
+        found: false,
+        query: args.query,
+        message: `Workspace '${root}' belum terindeks dalam Septum catalog.`,
+        suggested_action: {
+          tool: "septum_register_domain",
+          params: { name: "core", root: "src", ingest_now: true },
+        },
+        agent_guidance:
+          "Panggil tool 'septum_register_domain(name: \"core\", root: \"src\", ingest_now: true)' untuk mendaftarkan dan mengindeks codebase ini, atau jalankan 'septum init' di terminal workspace.",
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(diagnostic, null, 2),
+          },
+        ],
+        metadata: diagnostic,
+      };
+    }
+  }
+
   const locator = new SymbolLocator(repo);
-  const result: SymbolLocationResult = locator.locate(args.query, args.domain);
+  let result: SymbolLocationResult = locator.locate(args.query, args.domain);
+
+  // 2. JIT Delta Sync: Check if located file has changed on disk since last ingest
+  if (result.found && result.file_path && pipeline) {
+    const fullPath = isAbsolute(result.file_path)
+      ? result.file_path
+      : join(root, result.file_path);
+    try {
+      const reindexed = await pipeline.ingestFile(fullPath, config);
+      if (reindexed) {
+        result = locator.locate(args.query, args.domain);
+      }
+    } catch {
+      // Silently fall back to existing result
+    }
+  }
+
+  // 3. Fallback on Cache Miss: Search for candidate source files matching the query terms
+  if (!result.found && pipeline) {
+    try {
+      const cleanTerm = args.query.replace(/[^a-zA-Z0-9_]/g, " ").trim().split(/\s+/)[0] || "";
+      if (cleanTerm.length >= 3) {
+        const candidateFiles = findCandidateFiles(root, cleanTerm);
+        let anyReindexed = false;
+        for (const candidate of candidateFiles) {
+          const reindexed = await pipeline.ingestFile(candidate, config);
+          if (reindexed) anyReindexed = true;
+        }
+        if (anyReindexed) {
+          result = locator.locate(args.query, args.domain);
+        }
+      }
+    } catch {
+      // Ignore candidate scan errors
+    }
+  }
 
   let formattedText = "";
 
@@ -72,3 +149,42 @@ export function handleLocateSymbol(
     metadata: result,
   };
 }
+
+/**
+ * Searches for potential candidate files whose names resemble parts of the query term.
+ */
+function findCandidateFiles(root: string, term: string): string[] {
+  const matched: string[] = [];
+  const lowerTerm = term.toLowerCase().replace(/_/g, "");
+  const searchDirs = ["src", "app", "lib"].map((d) => join(root, d)).filter((d) => existsSync(d));
+
+  function scan(dir: string, depth: number = 0) {
+    if (depth > 4) return;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.name.startsWith(".") || e.name === "node_modules" || e.name === "dist") continue;
+        const full = join(dir, e.name);
+        if (e.isDirectory()) {
+          scan(full, depth + 1);
+        } else if (e.isFile() && /\.(ts|tsx|js|jsx|php|py|go)$/i.test(e.name)) {
+          const lowerName = e.name.toLowerCase().replace(/[-_.]/g, "");
+          if (lowerName.includes(lowerTerm) || lowerTerm.includes(lowerName.replace(/\.[^.]+$/, ""))) {
+            matched.push(full);
+            if (matched.length >= 5) return;
+          }
+        }
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  for (const sDir of searchDirs) {
+    scan(sDir);
+    if (matched.length >= 5) break;
+  }
+
+  return matched;
+}
+

package/src/mcp/tools/trace-vertical-slice.ts

@@ -18,7 +18,8 @@ export function handleTraceVerticalSlice(
     );
   }
 
-  const tracer = new VerticalSliceTracer(repo);
+  const workspaceRoot = (config.settings as Record<string, unknown>)?.workspace_root as string || process.cwd();
+  const tracer = new VerticalSliceTracer(repo, workspaceRoot);
   const result: VerticalSliceTraceResponse = tracer.trace(args.query);
 
   let formattedText = "";

package/src/types/index.ts

@@ -13,6 +13,7 @@ export type ArchetypeKind =
   | "request"
   | "resource"
   | "util"
+  | "view"
   | "unknown";
 
 export type SymbolKind =
@@ -23,7 +24,9 @@ export type SymbolKind =
   | "method"
   | "function"
   | "type"
-  | "property";
+  | "property"
+  | "component"
+  | "view";
 
 export type Visibility = "public" | "protected" | "private";