septum 0.1.4 → 0.1.5

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

@@ -1,190 +1,171 @@
-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,
-} from "../../core/resolver/symbol-locator.ts";
-
-export interface LocateSymbolArgs {
-  query: string;
-  domain?: string;
-  workspace_path?: string;
-}
-
-export async function handleLocateSymbol(
-  repo: SeptumRepository,
-  config: ValidatedSeptumConfig,
-  args: LocateSymbolArgs,
-  pipeline?: IngestionPipeline,
-  workspaceRoot?: string
-) {
-  if (!args.query) {
-    throw new Error(
-      "Missing required argument: 'query' (e.g. 'OrderController::calculateTotal' or error log snippet)"
-    );
-  }
-
-  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);
-  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 = "";
-
-  if (result.found) {
-    formattedText = `=== SYMBOL LOCATED ===\n`;
-    formattedText += `Status: FOUND (Exact Match)\n`;
-    formattedText += `File: ${result.file_path}\n`;
-    if (result.exact_symbol) {
-      formattedText += `Symbol: ${result.exact_symbol.name} [${result.exact_symbol.kind.toUpperCase()}]\n`;
-      formattedText += `Signature: ${result.exact_symbol.signature}\n`;
-      formattedText += `Lines: ${result.exact_symbol.line_start} - ${result.exact_symbol.line_end}\n`;
-    }
-    if (result.sibling_methods && result.sibling_methods.length > 0) {
-      formattedText += `\nSibling Methods in ${result.container_name || "Container"} (${result.sibling_methods.length}):\n`;
-      formattedText += `  ${result.sibling_methods.join(", ")}\n`;
-    }
-  } else {
-    formattedText = `=== SYMBOL NOT FOUND / DIAGNOSTIC RESOLUTION ===\n`;
-    formattedText += `Status: NOT FOUND\n`;
-    if (result.file_path) {
-      formattedText += `Target File: ${result.file_path}\n`;
-      formattedText += `Target Container: ${result.container_name || "Unknown"}\n`;
-    }
-    formattedText += `Message: ${result.message}\n`;
-
-    if (result.sibling_methods && result.sibling_methods.length > 0) {
-      formattedText += `\nExisting Methods in ${result.container_name || "Container"} (${result.sibling_methods.length}):\n`;
-      formattedText += `  ${result.sibling_methods.join(", ")}\n`;
-    }
-
-    if (result.suggestions.length > 0) {
-      formattedText += `\nTop Suggestions (Ranked by Similarity):\n`;
-      for (const sug of result.suggestions) {
-        const percent = Math.round(sug.similarity_score * 100);
-        formattedText += `  • ${sug.name} [${percent}% match] -> lines ${sug.line_start}-${sug.line_end} (${sug.signature})\n`;
-      }
-    }
-  }
-
-  return {
-    content: [
-      {
-        type: "text",
-        text: formattedText.trim(),
-      },
-    ],
-    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;
-}
-
+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,
+} from "../../core/resolver/symbol-locator.ts";
+
+export interface LocateSymbolArgs {
+  query?: string;
+  symbol?: string;
+  domain?: string;
+  workspace_path?: string;
+}
+
+export async function handleLocateSymbol(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: LocateSymbolArgs,
+  pipeline?: IngestionPipeline,
+  workspaceRoot?: string
+) {
+  const query = (args.query || args.symbol || "").toString().trim();
+  if (!query) {
+    throw new Error(
+      "Missing required argument: 'query' (e.g. 'OrderController::calculateTotal' or error log snippet)"
+    );
+  }
+
+  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,
+        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);
+  let result: SymbolLocationResult = locator.locate(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(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 = 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(query, args.domain);
+        }
+      }
+    } catch {
+      // Ignore candidate scan errors
+    }
+  }
+
+  const summary = result.found
+    ? `[FOUND] ${result.exact_symbol?.name || query} in ${result.file_path} (lines ${result.exact_symbol?.line_start}-${result.exact_symbol?.line_end})`
+    : `[NOT FOUND] Symbol '${query}' not found. ${result.suggestions.length > 0 ? `Top suggestions: ${result.suggestions.map((s) => s.name).slice(0, 3).join(", ")}` : "No close suggestions."}`;
+
+  const payload = {
+    status: result.found ? "success" : "not_found",
+    found: result.found,
+    query,
+    file_path: result.file_path || null,
+    container_name: result.container_name || null,
+    exact_symbol: result.exact_symbol || null,
+    sibling_methods: result.sibling_methods || [],
+    suggestions: result.suggestions || [],
+    summary,
+    message: result.message || summary,
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    metadata: payload,
+  };
+}
+
+/**
+ * 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/register-domain.ts

@@ -1,64 +1,68 @@
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
-import type { SeptumRepository } from "../../core/database/repository.ts";
-import { IngestionPipeline, type IngestionMetrics } from "../../core/ingestion/pipeline.ts";
-import type { DomainConfig } from "../../types/index.ts";
-
-export interface RegisterDomainArgs {
-  name: string;
-  root: string;
-  description?: string;
-  allowed_dependencies?: string[];
-  forbidden_dependencies?: string[];
-  archetypes?: Record<string, string>;
-  ingest_now?: boolean;
-}
-
-export async function handleRegisterDomain(
-  repo: SeptumRepository,
-  config: ValidatedSeptumConfig,
-  args: RegisterDomainArgs
-) {
-  if (!args.name || !args.root) {
-    throw new Error("Missing required arguments: 'name' and 'root' are required.");
-  }
-
-  const domainConfig = {
-    root: args.root,
-    description: args.description || `Domain: ${args.name}`,
-    allowed_dependencies: args.allowed_dependencies || [],
-    forbidden_dependencies: args.forbidden_dependencies || [],
-    archetypes: args.archetypes || {},
-  };
-
-  const domainId = repo.domains.upsertDomain(args.name, domainConfig);
-
-  config.domains[args.name] = domainConfig;
-
-  let ingestionMetrics: IngestionMetrics | null = null;
-  if (args.ingest_now) {
-    const pipeline = new IngestionPipeline(repo);
-    ingestionMetrics = await pipeline.run(config);
-  }
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: JSON.stringify(
-          {
-            status: "success",
-            message: `Domain '${args.name}' successfully registered in SQLite SSOT.${
-              args.ingest_now ? " Initial ingestion completed." : ""
-            }`,
-            domain_id: domainId,
-            domain: args.name,
-            config: domainConfig,
-            ...(ingestionMetrics ? { ingestion_metrics: ingestionMetrics } : {}),
-          },
-          null,
-          2
-        ),
-      },
-    ],
-  };
-}
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { IngestionPipeline, type IngestionMetrics } from "../../core/ingestion/pipeline.ts";
+import type { DomainConfig } from "../../types/index.ts";
+
+export interface RegisterDomainArgs {
+  domain?: string;
+  name?: string;
+  root: string;
+  description?: string;
+  allowed_dependencies?: string[];
+  forbidden_dependencies?: string[];
+  archetypes?: Record<string, string>;
+  ingest_now?: boolean;
+}
+
+export async function handleRegisterDomain(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: RegisterDomainArgs,
+  workspaceRoot: string = process.cwd()
+) {
+  const domainName = (args.domain || args.name || "").trim();
+  if (!domainName || !args.root) {
+    throw new Error("Missing required arguments: 'domain' (or 'name') and 'root' are required.");
+  }
+
+  const domainConfig = {
+    root: args.root,
+    description: args.description || `Domain: ${domainName}`,
+    allowed_dependencies: args.allowed_dependencies || [],
+    forbidden_dependencies: args.forbidden_dependencies || [],
+    archetypes: args.archetypes || {},
+  };
+
+  const domainId = repo.domains.upsertDomain(domainName, domainConfig);
+
+  config.domains[domainName] = domainConfig;
+
+  let ingestionMetrics: IngestionMetrics | null = null;
+  if (args.ingest_now) {
+    const pipeline = new IngestionPipeline(repo, workspaceRoot);
+    ingestionMetrics = await pipeline.run(config);
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            status: "success",
+            message: `Domain '${domainName}' successfully registered in SQLite SSOT.${
+              args.ingest_now ? " Initial ingestion completed." : ""
+            }`,
+            domain_id: domainId,
+            domain: domainName,
+            name: domainName,
+            config: domainConfig,
+            ...(ingestionMetrics ? { ingestion_metrics: ingestionMetrics } : {}),
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}

package/src/mcp/tools/register-feature.ts

@@ -0,0 +1,100 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { SessionManager } from "../../core/session/session-manager.ts";
+import type { FeatureConfig, RegisterFeatureArgs } from "../../types/index.ts";
+
+export async function handleRegisterFeature(
+  _repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: RegisterFeatureArgs,
+  workspaceRoot: string = process.cwd()
+) {
+  const featureKey = (args.feature_key || (args as unknown as Record<string, unknown>).feature || "").toString().trim();
+  const domain = (args.domain || (args as unknown as Record<string, unknown>).domain_name || "").toString().trim();
+
+  if (!featureKey || !domain) {
+    throw new Error("Missing required arguments: 'feature_key' and 'domain' are required.");
+  }
+
+  const rawTouchpoints = args.allowed_touchpoints ?? [];
+  const allowedTouchpoints = Array.isArray(rawTouchpoints)
+    ? rawTouchpoints
+    : typeof rawTouchpoints === "string"
+    ? [rawTouchpoints]
+    : [];
+
+  const rawReuse = args.reuse_symbols;
+  const reuseSymbols: string[] = Array.isArray(rawReuse)
+    ? rawReuse
+    : typeof rawReuse === "string"
+    ? [rawReuse]
+    : [];
+
+  const featureConfig = {
+    domain,
+    description: args.description || `Feature: ${featureKey}`,
+    allowed_touchpoints: allowedTouchpoints,
+    reuse_symbols: reuseSymbols,
+    input_contract: args.input_contract || {},
+    output_contract: args.output_contract || {},
+  };
+
+  if (!config.features) {
+    config.features = {};
+  }
+  config.features[featureKey] = featureConfig;
+
+  // Record Active Feature Session Lease (.septum/session.json)
+  SessionManager.saveActiveSession(workspaceRoot, {
+    feature_key: featureKey,
+    domain,
+    touchpoints: featureConfig.allowed_touchpoints,
+    locked_at: new Date().toISOString(),
+  });
+
+  let persisted = false;
+  if (args.persist_to_config) {
+    try {
+      const configPath = path.resolve(workspaceRoot, "septum.config.json");
+      let diskConfig: Record<string, unknown> = {};
+      if (fs.existsSync(configPath)) {
+        diskConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      }
+      if (!diskConfig.features || typeof diskConfig.features !== "object") {
+        diskConfig.features = {};
+      }
+      (diskConfig.features as Record<string, unknown>)[featureKey] = featureConfig;
+      fs.writeFileSync(configPath, JSON.stringify(diskConfig, null, 2), "utf-8");
+      persisted = true;
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[Septum Warning] Failed to persist feature to septum.config.json: ${msg}`);
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            status: "success",
+            message: `Feature '${featureKey}' successfully registered and session lease established.${
+              persisted ? " Persisted to septum.config.json." : ""
+            }`,
+            feature_key: featureKey,
+            feature: featureKey,
+            domain,
+            touchpoints: featureConfig.allowed_touchpoints,
+            reuse_symbols: featureConfig.reuse_symbols,
+            persisted_to_disk: persisted,
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}