septum 0.1.4 → 0.1.6

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

@@ -1,121 +1,155 @@
-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;
-  workspace_path?: string;
-}
-
-export function handleGetDomainCatalog(
-  repo: SeptumRepository,
-  config: ValidatedSeptumConfig,
-  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";
-    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 {}
-}
+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 type { DomainCatalogResponse } from "../../types/index.ts";
+import type { GetDomainCatalogArgs } from "../schemas.ts";
+
+export type { GetDomainCatalogArgs } from "../schemas.ts";
+
+export function handleGetDomainCatalog(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: GetDomainCatalogArgs,
+  workspaceRoot?: string
+) {
+  const targetRoot = args.workspace_path || workspaceRoot || (repo as any)?.projectRoot || process.cwd();
+  const domainName = args.domain ?? args.name;
+
+  if (!domainName) {
+    const allDomains = repo.getAllDomains();
+    if (allDomains.length === 0) {
+      const root = targetRoot;
+      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";
+    const totalSlices =
+      typeof (repo as any).countVerticalSlices === "function"
+        ? (repo as any).countVerticalSlices()
+        : 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 archetypeFilter = args.archetype_filter ?? args.archetype;
+  const detailLevel = args.detail_level ?? "compact";
+  const fileFilter = args.file_filter;
+
+  const catalog: DomainCatalogResponse | null = (repo.getDomainCatalog as any)(
+    domainName,
+    archetypeFilter,
+    { detailLevel, fileFilter }
+  );
+  if (!catalog) {
+    const available = Object.keys(config.domains || {});
+    const suggestions = available.filter((d) =>
+      d.toLowerCase().includes(domainName.toLowerCase()) ||
+      domainName.toLowerCase().includes(d.toLowerCase())
+    );
+    const notFoundPayload = {
+      status: "not_found",
+      found: false,
+      domain: domainName,
+      message: `Domain '${domainName}' not found in Septum catalog.`,
+      available_domains: available,
+      suggestions: suggestions.length > 0 ? suggestions : available,
+      suggested_action: {
+        tool: "septum_register_domain",
+        params: { domain: domainName, root: `src/domains/${domainName}` },
+      },
+    };
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(notFoundPayload, null, 2),
+        },
+      ],
+      metadata: notFoundPayload,
+    };
+  }
+
+  // Record access log for Gate 3 (Mandatory Catalog Consultation)
+  recordCatalogAccess(domainName, targetRoot);
+
+  // 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, projectRoot: string = process.cwd()): void {
+  try {
+    const septumDir = path.resolve(projectRoot, ".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-environment-topology.ts

@@ -1,13 +1,10 @@
 import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
 import type { SeptumRepository } from "../../core/database/repository.ts";
 import { EnvironmentDetector } from "../../core/topology/environment-detector.ts";
-import type { EnvironmentLayer, ResolveLayerInput, ResolveNodeInput } from "../../core/topology/types.ts";
+import type { EnvironmentLayer } from "../../core/topology/types.ts";
+import type { GetEnvironmentTopologyArgs } from "../schemas.ts";
 
-export interface GetEnvironmentTopologyArgs {
-  resolve?: ResolveLayerInput;
-  resolveNode?: ResolveNodeInput;
-  refresh?: boolean;
-}
+export type { GetEnvironmentTopologyArgs } from "../schemas.ts";
 
 export function handleGetEnvironmentTopology(
   repo: SeptumRepository,

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

@@ -1,116 +1,227 @@
-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 {}
-}
+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";
+import type { GetFeatureContextArgs } from "../schemas.ts";
+
+export type { GetFeatureContextArgs } from "../schemas.ts";
+
+export function handleClearFeatureContext(workspaceRoot: string = process.cwd()): boolean {
+  return SessionManager.clearActiveSession(workspaceRoot);
+}
+
+export function handleGetFeatureContext(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: GetFeatureContextArgs,
+  workspaceRoot: string = process.cwd()
+) {
+  const featureKey = (args.feature_key || args.feature || "").trim();
+  const features = { ...(config.features ?? {}) };
+  if (typeof repo?.getMeta === "function") {
+    try {
+      const metaFeaturesRaw = repo.getMeta("features_json");
+      if (metaFeaturesRaw) {
+        Object.assign(features, JSON.parse(metaFeaturesRaw));
+      }
+    } catch {}
+  }
+
+  // ZERO-ARGUMENT GRACEFUL FALLBACK: Guide the agent instead of throwing validation errors
+  if (!featureKey) {
+    const available = Object.keys(features);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            {
+              status: "prompt",
+              message: "No feature specified. Please specify 'feature_key' from the registered features below or trace routes.",
+              available_features: available.length > 0 ? available : [],
+              instructions: "Call 'septum_get_feature_context({ feature_key: \"<name>\" })' or register a new feature with 'septum_register_feature'.",
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  let featureConfig = features[featureKey];
+  let isInferred = false;
+
+  if (!featureConfig) {
+    // Attempt auto-derive from vertical slices or domain symbols
+    const searchTerm = featureKey.toLowerCase();
+    const allSlices = typeof repo.getAllVerticalSlices === "function" ? repo.getAllVerticalSlices() : [];
+    const fromRepoSearch = typeof repo.findVerticalSlices === "function" ? repo.findVerticalSlices(searchTerm) : [];
+    const matchingSlices = [
+      ...fromRepoSearch,
+      ...allSlices.filter(
+        (s) =>
+          s.route_uri.toLowerCase().includes(searchTerm) ||
+          (s.route_name && s.route_name.toLowerCase().includes(searchTerm)) ||
+          s.controller_class.toLowerCase().includes(searchTerm) ||
+          (s.feature_key && s.feature_key.toLowerCase().includes(searchTerm))
+      ),
+    ];
+
+    const uniqueSlices = Array.from(
+      new Map(matchingSlices.map((s) => [`${s.http_method}:${s.route_uri}`, s])).values()
+    );
+
+    if (uniqueSlices.length > 0) {
+      isInferred = true;
+      const candidateTouchpoints = new Set<string>();
+      const candidateSymbols = new Set<string>();
+      let detectedDomain = "app";
+
+      if (config.domains && config.domains[featureKey]) {
+        detectedDomain = featureKey;
+      }
+
+      for (const slice of uniqueSlices) {
+        if (slice.controller_file) {
+          candidateTouchpoints.add(slice.controller_file);
+        }
+        candidateSymbols.add(slice.controller_class);
+        if (slice.action_name) {
+          candidateSymbols.add(`${slice.controller_class}@${slice.action_name}`);
+        }
+
+        if (slice.execution_chain_json) {
+          try {
+            const chain = JSON.parse(slice.execution_chain_json);
+            if (Array.isArray(chain)) {
+              for (const node of chain) {
+                if (node.file) candidateTouchpoints.add(node.file);
+                if (node.symbol) candidateSymbols.add(node.symbol);
+              }
+            }
+          } catch {}
+        }
+      }
+
+      featureConfig = {
+        domain: detectedDomain,
+        description: `[Auto-Derived] Feature context inferred from ${uniqueSlices.length} vertical slices matching '${featureKey}'`,
+        allowed_touchpoints: Array.from(candidateTouchpoints),
+        reuse_symbols: Array.from(candidateSymbols).slice(0, 10),
+        input_contract: {},
+        output_contract: {},
+      };
+    } else {
+      const available = Object.keys(features);
+      const availableStr = available.length > 0 ? available.join(", ") : "none";
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              {
+                status: "not_found",
+                feature_key: featureKey,
+                message: `Feature '${featureKey}' not found in configuration or vertical slices. Available features: [${availableStr}].`,
+                recovery_options: [
+                  `septum_register_feature({ feature_key: "${featureKey}", domain: "<domain_name>", allowed_touchpoints: ["path/to/file"] })`,
+                  `septum_trace_vertical_slice({ entry_file: "routes/web.php" })`,
+                ],
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+
+  // Record Active Feature Session Lease (.septum/session.json)
+  SessionManager.saveActiveSession(workspaceRoot, {
+    feature_key: featureKey,
+    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_key: featureKey,
+    feature: featureKey,
+    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.",
+    ],
+    ...(isInferred ? { is_inferred: true } : {}),
+  };
+
+  recordFeatureAccess(featureConfig.domain, featureKey, workspaceRoot);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(response, null, 2),
+      },
+    ],
+  };
+}
+
+function recordFeatureAccess(domain: string, feature: string, workspaceRoot: string = process.cwd()): void {
+  try {
+    const septumDir = path.resolve(workspaceRoot, ".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 {}
+}
+