septum 0.1.0

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

@@ -0,0 +1,91 @@
+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";
+
+export interface GetDomainCatalogArgs {
+  domain?: string;
+  archetype_filter?: string;
+}
+
+export function handleGetDomainCatalog(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: GetDomainCatalogArgs
+) {
+  if (!args.domain) {
+    const allDomains = repo.getAllDomains();
+    const projectType = repo.getMeta("project_type") || "generic";
+    const framework = repo.getMeta("framework") || "unknown";
+    const archStyle = repo.getMeta("architecture_style") || "modular";
+    const totalSlices = repo.getAllVerticalSlices().length;
+
+    const macroMap = {
+      telescope_view: {
+        project_type: projectType,
+        framework,
+        architecture_style: archStyle,
+        total_domains: allDomains.length,
+        total_vertical_slices: totalSlices,
+      },
+      domains: allDomains.map((d) => ({
+        name: d.name,
+        root: d.root_path,
+        archetypes: Object.keys(JSON.parse(d.archetypes_json || "{}")),
+        allowed_dependencies: JSON.parse(d.allowed_deps_json || "[]"),
+        forbidden_dependencies: JSON.parse(d.forbidden_deps_json || "[]"),
+      })),
+      agent_instruction:
+        "Macro semantic map loaded from SQLite SSOT. Use 'septum_get_domain_catalog' with domain='<name>' for granular file/symbol catalogs, or 'septum_trace_vertical_slice' with query='<route|command|intent>' for end-to-end execution flow.",
+    };
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(macroMap, null, 2),
+        },
+      ],
+    };
+  }
+
+  const catalog = repo.getDomainCatalog(args.domain, args.archetype_filter);
+  if (!catalog) {
+    const available = Object.keys(config.domains).join(", ");
+    throw new Error(
+      `Domain '${args.domain}' not found. Available domains in Septum catalog: [${available}]. Run 'septum ingest' or 'septum_register_domain' if recently added.`
+    );
+  }
+
+  // Record access log for Gate 3 (Mandatory Catalog Consultation)
+  recordCatalogAccess(args.domain);
+
+  // Token-efficient serialization: keep payload dense and under 500 tokens
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(catalog, null, 2),
+      },
+    ],
+  };
+}
+
+function recordCatalogAccess(domain: string): void {
+  try {
+    const septumDir = path.resolve(process.cwd(), ".septum");
+    if (!fs.existsSync(septumDir)) {
+      fs.mkdirSync(septumDir, { recursive: true });
+    }
+    const logPath = path.join(septumDir, "catalog_access.json");
+    let log: { domains?: Record<string, string>; features?: Record<string, string> } = {};
+    if (fs.existsSync(logPath)) {
+      try {
+        log = JSON.parse(fs.readFileSync(logPath, "utf-8"));
+      } catch {}
+    }
+    log.domains = log.domains || {};
+    log.domains[domain] = new Date().toISOString();
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), "utf-8");
+  } catch {}
+}

package/src/mcp/tools/get-feature-context.ts

@@ -0,0 +1,116 @@
+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 { FeatureContextResponse } from "../../types/index.ts";
+
+export interface GetFeatureContextArgs {
+  feature: string;
+}
+
+export function handleClearFeatureContext(workspaceRoot: string = process.cwd()): boolean {
+  return SessionManager.clearActiveSession(workspaceRoot);
+}
+
+export function handleGetFeatureContext(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: GetFeatureContextArgs
+) {
+  if (!args.feature) {
+    throw new Error("Missing required argument: 'feature'");
+  }
+
+  const features = config.features ?? {};
+  const featureConfig = features[args.feature];
+
+  if (!featureConfig) {
+    const available = Object.keys(features).join(", ") || "none";
+    throw new Error(
+      `Feature '${args.feature}' not found in configuration. Available features: [${available}]`
+    );
+  }
+
+  // Record Active Feature Session Lease (.septum/session.json)
+  SessionManager.saveActiveSession(process.cwd(), {
+    feature_key: args.feature,
+    domain: featureConfig.domain,
+    touchpoints: featureConfig.allowed_touchpoints ?? [],
+    locked_at: new Date().toISOString(),
+  });
+
+  // Deterministically fetch signatures, methods, and properties for reuse_symbols from SQLite
+  const reuseSymbolsWithMeta: FeatureContextResponse["reuse_symbols"] = [];
+  const requestedSymbols = featureConfig.reuse_symbols ?? [];
+
+  for (const symName of requestedSymbols) {
+    const record = repo.findSymbolWithMembers(symName);
+    if (record) {
+      reuseSymbolsWithMeta.push({
+        name: record.symbol_name,
+        kind: record.kind,
+        signature: record.signature,
+        methods: record.methods.length > 0 ? record.methods : undefined,
+        properties: record.properties.length > 0 ? record.properties : undefined,
+        file_path: record.file_path,
+        domain: record.domain_name,
+      });
+    } else {
+      reuseSymbolsWithMeta.push({
+        name: symName,
+        kind: "unknown",
+        domain: featureConfig.domain,
+      });
+    }
+  }
+
+  const response: FeatureContextResponse = {
+    feature: args.feature,
+    domain: featureConfig.domain,
+    description: featureConfig.description,
+    allowed_touchpoints: featureConfig.allowed_touchpoints,
+    reuse_symbols: reuseSymbolsWithMeta,
+    input_contract: (featureConfig.input_contract as Record<string, unknown>) ?? {},
+    output_contract: (featureConfig.output_contract as Record<string, unknown>) ?? {},
+    governance_directives: [
+      "DO NOT modify or edit any files outside allowed_touchpoints.",
+      "DO NOT create duplicate helpers/services; reuse the existing symbols and methods declared in reuse_symbols.",
+      "DO NOT emit or expect phantom payload fields outside input_contract and output_contract.",
+      "DO NOT import cross-domain modules without declared allowed_dependencies in Septum domain boundaries.",
+    ],
+  };
+
+  recordFeatureAccess(featureConfig.domain, args.feature);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(response, null, 2),
+      },
+    ],
+  };
+}
+
+function recordFeatureAccess(domain: string, feature: string): void {
+  try {
+    const septumDir = path.resolve(process.cwd(), ".septum");
+    if (!fs.existsSync(septumDir)) {
+      fs.mkdirSync(septumDir, { recursive: true });
+    }
+    const logPath = path.join(septumDir, "catalog_access.json");
+    let log: { domains?: Record<string, string>; features?: Record<string, string> } = {};
+    if (fs.existsSync(logPath)) {
+      try {
+        log = JSON.parse(fs.readFileSync(logPath, "utf-8"));
+      } catch {}
+    }
+    log.domains = log.domains || {};
+    log.features = log.features || {};
+    const now = new Date().toISOString();
+    log.domains[domain] = now;
+    log.features[feature] = now;
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), "utf-8");
+  } catch {}
+}

package/src/mcp/tools/get-symbol-hotspots.ts

@@ -0,0 +1,49 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { DatabaseRepository } from "../../core/database/repository.ts";
+import type { SymbolKind } from "../../types/index.ts";
+
+export interface GetSymbolHotspotsArgs {
+  min_lines?: number;
+  kind?: SymbolKind;
+  domain?: string;
+  limit?: number;
+}
+
+export function handleGetSymbolHotspots(
+  repo: DatabaseRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetSymbolHotspotsArgs
+) {
+  const minLines = args.min_lines ?? 30;
+  const limit = args.limit ?? 30;
+
+  const hotspots = repo.getHotspotSymbols({
+    minLines,
+    kind: args.kind,
+    domain: args.domain,
+    limit,
+  });
+
+  const payload = {
+    total_found: hotspots.length,
+    threshold_min_lines: minLines,
+    hotspots: hotspots.map((h) => ({
+      name: h.name,
+      kind: h.kind,
+      line_count: h.line_count,
+      line_span: `${h.line_start}-${h.line_end}`,
+      file_path: h.file_path,
+      domain: h.domain_name,
+      signature: h.signature,
+    })),
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}

package/src/mcp/tools/get-symbol-impact.ts

@@ -0,0 +1,26 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import type { GetSymbolImpactArgs } from "../../types/index.ts";
+
+export function handleGetSymbolImpact(
+  repo: SeptumRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetSymbolImpactArgs
+) {
+  if (!args.symbol) {
+    throw new Error(
+      "Missing required argument: 'symbol' (e.g. 'OrderService::cancelOrder', 'OrderService', or 'cancelOrder')"
+    );
+  }
+
+  const impact = repo.getSymbolImpact(args.symbol);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(impact, null, 2),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,63 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { SymbolLocator } from "../../core/resolver/symbol-locator.ts";
+import type { GetSymbolArgs } from "../../types/index.ts";
+
+export function handleGetSymbol(
+  repo: SeptumRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetSymbolArgs
+) {
+  if (!args.symbol) {
+    throw new Error(
+      "Missing required argument: 'symbol' (e.g. 'OrderController::cancelOrder', 'OrderService', or 'cancelOrder')"
+    );
+  }
+
+  const details = repo.getSymbolDetails(args.symbol, {
+    domain: args.domain,
+    includeDependencies: args.include_dependencies,
+  });
+
+  if (details) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(details, null, 2),
+        },
+      ],
+    };
+  }
+
+  // Fallback to fuzzy SymbolLocator to provide actionable hints
+  const locator = new SymbolLocator(repo);
+  const fallback = locator.locate(args.symbol, args.domain);
+
+  const payload = {
+    symbol: args.symbol,
+    found: false,
+    message: `Symbol '${args.symbol}' was not found in the deterministic catalog.`,
+    suggestions: fallback.suggestions.map((s) => ({
+      name: s.name,
+      similarity_score: Math.round(s.similarity_score * 100) / 100,
+      exact_range: {
+        start_line: s.line_start,
+        end_line: s.line_end,
+        total_lines: s.line_end - s.line_start + 1,
+      },
+      signature: s.signature,
+      file_path: s.file_path,
+    })),
+    sibling_methods: fallback.sibling_methods,
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,74 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import {
+  SymbolLocator,
+  type SymbolLocationResult,
+} from "../../core/resolver/symbol-locator.ts";
+
+export interface LocateSymbolArgs {
+  query: string;
+  domain?: string;
+}
+
+export function handleLocateSymbol(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: LocateSymbolArgs
+) {
+  if (!args.query) {
+    throw new Error(
+      "Missing required argument: 'query' (e.g. 'OrderController::calculateTotal' or error log snippet)"
+    );
+  }
+
+  const locator = new SymbolLocator(repo);
+  const result: SymbolLocationResult = locator.locate(args.query, args.domain);
+
+  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,
+  };
+}

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

@@ -0,0 +1,64 @@
+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: 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
+        ),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,102 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { VerticalSliceTracer } from "../../core/resolver/vertical-slice-tracer.ts";
+import type { VerticalSliceTraceResponse } from "../../types/index.ts";
+
+export interface TraceVerticalSliceArgs {
+  query: string;
+}
+
+export function handleTraceVerticalSlice(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: TraceVerticalSliceArgs
+) {
+  if (!args.query) {
+    throw new Error(
+      "Missing required argument: 'query' (e.g. 'POST /orders/{id}/status', 'OrderController@updateStatus', or task intent 'Ubah status order di dashboard')"
+    );
+  }
+
+  const tracer = new VerticalSliceTracer(repo);
+  const result: VerticalSliceTraceResponse = tracer.trace(args.query);
+
+  let formattedText = "";
+
+  if (result.found && result.slice) {
+    const s = result.slice;
+    formattedText = `=== VERTICAL SLICE TRACE ===\n`;
+    formattedText += `Query: ${result.query}\n`;
+    formattedText += `Status: RESOLVED\n\n`;
+
+    formattedText += `• Route:\n`;
+    formattedText += `    Method: ${s.route.method}\n`;
+    formattedText += `    URI:    ${s.route.uri}\n`;
+    if (s.route.name) {
+      formattedText += `    Name:   ${s.route.name}\n`;
+    }
+
+    if (s.request) {
+      formattedText += `\n• Request / Validation:\n`;
+      formattedText += `    Class:  ${s.request.class} (${s.request.file || "inline"})\n`;
+      const ruleKeys = Object.keys(s.request.rules);
+      if (ruleKeys.length > 0) {
+        formattedText += `    Rules:\n`;
+        for (const k of ruleKeys) {
+          formattedText += `      - ${k} => ${s.request.rules[k]}\n`;
+        }
+      }
+    }
+
+    formattedText += `\n• Controller Action:\n`;
+    formattedText += `    Class:  ${s.controller.class}@${s.controller.action}\n`;
+    formattedText += `    File:   ${s.controller.file || "unknown"}:${s.controller.line}\n`;
+
+    if (s.model) {
+      formattedText += `\n• Model:\n`;
+      formattedText += `    Class:  ${s.model.class} (${s.model.file || "unknown"})\n`;
+      if (s.model.fillable && s.model.fillable.length > 0) {
+        formattedText += `    Fillable: [${s.model.fillable.join(", ")}]\n`;
+      }
+      if (s.model.casts && Object.keys(s.model.casts).length > 0) {
+        formattedText += `    Casts:    ${JSON.stringify(s.model.casts)}\n`;
+      }
+    }
+
+    if (s.frontend) {
+      formattedText += `\n• Frontend Target:\n`;
+      formattedText += `    Page:   ${s.frontend.target}\n`;
+      if (s.frontend.props.length > 0) {
+        formattedText += `    Props:  [${s.frontend.props.join(", ")}]\n`;
+      }
+    }
+
+    if (result.alternatives && result.alternatives.length > 0) {
+      formattedText += `\n• Other Matching Slices:\n`;
+      for (const alt of result.alternatives) {
+        formattedText += `    - ${alt.method} ${alt.uri} -> ${alt.controller}@${alt.action}\n`;
+      }
+    }
+  } else {
+    formattedText = `=== VERTICAL SLICE NOT FOUND ===\n`;
+    formattedText += `Query: ${result.query}\n`;
+    formattedText += `Message: ${result.message}\n`;
+
+    if (result.alternatives && result.alternatives.length > 0) {
+      formattedText += `\nAvailable Slices:\n`;
+      for (const alt of result.alternatives) {
+        formattedText += `    - ${alt.method} ${alt.uri} -> ${alt.controller}@${alt.action}\n`;
+      }
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: formattedText.trim(),
+      },
+    ],
+    metadata: result,
+  };
+}