septum 0.1.7 → 0.1.8

package/src/mcp/tools/symbol.ts

@@ -0,0 +1,82 @@
+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 type { SymbolToolArgs } from "../schemas.ts";
+import { handleLocateSymbol } from "./locate-symbol.ts";
+import { handleGetSymbol } from "./get-symbol.ts";
+import { handleGetSymbolImpact } from "./get-symbol-impact.ts";
+import { handleGetSymbolHotspots } from "./get-symbol-hotspots.ts";
+
+export type { SymbolToolArgs };
+
+export async function handleSymbolTool(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: SymbolToolArgs,
+  pipeline?: IngestionPipeline,
+  workspaceRoot?: string
+) {
+  const action = args.action || "locate";
+
+  switch (action) {
+    case "inspect": {
+      const symbol = args.symbol || args.query || "";
+      return handleGetSymbol(
+        repo,
+        config,
+        {
+          symbol,
+          query: symbol,
+          domain: args.domain,
+          include_dependencies: args.include_dependencies,
+        },
+        workspaceRoot
+      );
+    }
+
+    case "impact": {
+      const symbol = args.symbol || args.query || "";
+      return handleGetSymbolImpact(
+        repo,
+        config,
+        {
+          symbol,
+          query: symbol,
+          domain: args.domain,
+        },
+        workspaceRoot
+      );
+    }
+
+    case "hotspots":
+      return handleGetSymbolHotspots(
+        repo,
+        config,
+        {
+          min_lines: args.min_lines,
+          min_nesting: args.min_nesting,
+          kind: args.kind,
+          domain: args.domain,
+          limit: args.limit ?? 30,
+          sort_by: (args.sort_by === "line_count" ? "lines" : args.sort_by) as any,
+          workspace_path: args.workspace_path,
+        },
+        workspaceRoot
+      );
+
+    case "locate":
+    default:
+      return await handleLocateSymbol(
+        repo,
+        config,
+        {
+          query: args.query || args.symbol || "",
+          domain: args.domain,
+          limit: args.limit ?? 10,
+          workspace_path: args.workspace_path,
+        },
+        pipeline,
+        workspaceRoot
+      );
+  }
+}

package/src/mcp/workspace-manager.ts

@@ -0,0 +1,159 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { ConfigLoader } from '../core/config/loader.ts';
+import type { ValidatedSeptumConfig } from '../core/config/schema.ts';
+import { SeptumDatabase } from '../core/database/client.ts';
+import { SeptumRepository } from '../core/database/repository.ts';
+import { BoundaryEvaluator } from '../core/boundary/evaluator.ts';
+import { ModuleResolver } from '../core/resolver/module-resolver.ts';
+import { findProjectRoot, isAppHostDirectory, isPathContained, PROJECT_ROOT_MARKERS, setLastKnownProjectRoot } from '../core/resolver/path-resolver.ts';
+import { IngestionPipeline } from '../core/ingestion/pipeline.ts';
+import { RESOURCE_LIMITS } from '../core/resources/limits.ts';
+import { SerialWorkQueue } from '../core/resources/work-queue.ts';
+import { WatchBudget, WorkspaceWatcher } from './workspace-watcher.ts';
+
+export function resolveServerWorkspace(options: {workspacePath?: string; filePath?: string; fallbackRoot?: string; knownRoots?: string[]; initial?: boolean; cwd?: string} = {}): string {
+  const cwd = options.cwd || process.cwd();
+  const explicit = options.workspacePath || (!options.filePath ? process.env.SEPTUM_WORKSPACE_ROOT || process.env.WORKSPACE_ROOT : undefined);
+  let root: string;
+  if (explicit) {
+    root = resolve(cwd, explicit);
+  } else if (options.filePath && (isAbsolute(options.filePath) || /[\\/]/.test(options.filePath))) {
+    const absTarget = resolve(options.fallbackRoot || cwd, options.filePath);
+    // SV-04: Prefer known/registered workspace roots that already contain this file before falling back to nested markers
+    const containingKnown = options.knownRoots?.find(known => isPathContained(absTarget, known));
+    if (containingKnown && isWorkspaceInitialized(containingKnown)) {
+      root = containingKnown;
+    } else {
+      root = findProjectRoot(absTarget);
+    }
+  } else if (options.fallbackRoot) {
+    root = options.fallbackRoot;
+  } else {
+    if (!PROJECT_ROOT_MARKERS.some(marker => existsSync(join(cwd, marker)))) throw new Error('No project marker in CWD. Set SEPTUM_WORKSPACE_ROOT to an explicit workspace directory.');
+    root = cwd;
+  }
+  root = realpathSync(root);
+  if (!statSync(root).isDirectory() || root === dirname(root) || root === realpathSync(homedir()) || isAppHostDirectory(root)) throw new Error(`Unsafe Septum serve workspace: ${root}`);
+
+  // SV-04: Validate file-workspace consistency when both are present
+  if (options.workspacePath && options.filePath && isAbsolute(options.filePath)) {
+    if (!isPathContained(options.filePath, root)) {
+      throw new Error(`File '${options.filePath}' does not belong to workspace '${root}'.`);
+    }
+  }
+
+  setLastKnownProjectRoot(root);
+  return root;
+}
+
+export function isWorkspaceInitialized(root: string): boolean {
+  try {
+    // SV-03: Pure .septum directory without config or db is uninitialized
+    return existsSync(join(root, "septum.config.json")) ||
+           existsSync(join(root, ".septum", "septum.db"));
+  } catch {
+    return false;
+  }
+}
+
+export interface WorkspaceContext {
+  root: string;
+  config: ValidatedSeptumConfig;
+  db: SeptumDatabase;
+  repo: SeptumRepository;
+  evaluator: BoundaryEvaluator;
+  pipeline: IngestionPipeline;
+  ready: Promise<void>;
+  watcher: WorkspaceWatcher;
+}
+interface Entry { context: WorkspaceContext; leases: number; lastUsed: number; initializing: boolean; abort: AbortController; disposal?: Promise<void> }
+export interface WorkspaceLease { context: WorkspaceContext; release(): void }
+
+export class WorkspaceManager {
+  private contexts = new Map<string, Entry>();
+  private queue = new SerialWorkQueue();
+  private budget = new WatchBudget();
+  private disposals = new Set<Promise<void>>();
+  private closed = false;
+  private closing: Promise<void> | null = null;
+  private idleTimer: ReturnType<typeof setInterval>;
+  initialRoot?: string;
+  lastRoot?: string;
+  get activeRoots(): string[] { return [...this.contexts.keys()]; }
+  constructor(private readonly now: () => number = Date.now) {
+    this.idleTimer = setInterval(() => { void this.expireIdle().catch(error => console.error(`[Septum Cleanup Warning] ${String(error)}`)); }, 60_000);
+    this.idleTimer.unref();
+  }
+  get size(): number { return this.contexts.size; }
+  get watchCount(): number { return this.budget.count; }
+  get syncDurationMs(): number { return Math.max(0, ...[...this.contexts.values()].map(entry => Number(entry.context.repo.getMeta("sync_duration_ms") || 0))); }
+  get pendingPaths(): number { return [...this.contexts.values()].reduce((n, entry) => n + entry.context.watcher.pendingCount, 0); }
+
+  acquire(rawRoot: string): WorkspaceLease {
+    if (this.closed) throw new Error('Septum server is shutting down');
+    const root = realpathSync(rawRoot);
+    let entry = this.contexts.get(root);
+    if (!entry) {
+      if (this.contexts.size >= RESOURCE_LIMITS.workspaces) {
+        const idle = [...this.contexts.values()].filter(value => !value.leases && !value.initializing && !value.context.watcher.isBusy).sort((a,b) => a.lastUsed - b.lastUsed)[0];
+        if (!idle) throw new Error('Workspace resource limit reached: all workspace slots are busy. Retry after active requests finish.');
+        this.dispose(idle);
+      }
+      const config = ConfigLoader.load(undefined, root);
+      const db = new SeptumDatabase(resolve(root, config.settings.db_path || '.septum/septum.db'));
+      try {
+        const repo = new SeptumRepository(db.raw);
+        const pipeline = new IngestionPipeline(repo, root);
+        const evaluator = new BoundaryEvaluator(repo, new ModuleResolver(root, repo));
+        const abort = new AbortController();
+        const ready = this.queue.run(async () => { abort.signal.throwIfAborted(); await pipeline.run(config, {verifyContent:true,signal:abort.signal}); });
+        const watcher = new WorkspaceWatcher(root, repo, pipeline, ready, this.queue, this.budget, () => ConfigLoader.load(undefined, root));
+        entry = {context:{root,config,db,repo,evaluator,pipeline,ready,watcher},leases:0,lastUsed:this.now(),initializing:true,abort};
+        this.contexts.set(root, entry);
+        const initialized = entry;
+        void ready.then(() => { initialized.initializing = false; }, () => { initialized.initializing = false; this.dispose(initialized); });
+      } catch (error) { db.close(); throw error; }
+    }
+    this.lastRoot = root;
+    entry.leases++; entry.lastUsed = this.now();
+    const leased = entry; let released = false;
+    return {context: entry.context, release: () => { if (!released) { released=true; leased.leases--; leased.lastUsed=this.now(); } }};
+  }
+
+  private dispose(entry: Entry): Promise<void> {
+    if (entry.disposal) return entry.disposal;
+    if (this.contexts.get(entry.context.root) === entry) this.contexts.delete(entry.context.root);
+    entry.abort.abort();
+    const idle = !entry.leases && !entry.initializing && !entry.context.watcher.isBusy;
+    const stop = entry.context.watcher.close();
+    // Eviction of an idle context closes its database before admitting another.
+    if (idle) entry.context.db.close();
+    const disposal = stop.then(async () => { if (!idle) { await this.queue.drain(); entry.context.db.close(); } });
+    entry.disposal = disposal;
+    this.disposals.add(disposal);
+    void disposal.finally(() => this.disposals.delete(disposal)).catch(error => console.error(`[Septum Cleanup Warning] ${String(error)}`));
+    return disposal;
+  }
+
+  async expireIdle(): Promise<void> {
+    const expired = [...this.contexts.values()].filter(entry => !entry.leases && !entry.initializing && !entry.context.watcher.isBusy && this.now() - entry.lastUsed >= RESOURCE_LIMITS.workspaceIdleMs);
+    await Promise.all(expired.map(entry => this.dispose(entry)));
+  }
+
+  runTool<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    return this.queue.run(() => { if (this.closed) throw new Error("Septum server is shutting down"); return work(); }, signal);
+  }
+
+  close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true; clearInterval(this.idleTimer);
+    const pending = [...this.contexts.values()].map(entry => this.dispose(entry));
+    this.closing = Promise.allSettled([...pending, ...this.disposals, this.queue.drain()]).then(results => {
+      const failed = results.find(result => result.status === 'rejected');
+      if (failed?.status === 'rejected') throw failed.reason;
+    });
+    return this.closing;
+  }
+}

package/src/mcp/workspace-watcher.ts

@@ -0,0 +1,202 @@
+import { existsSync, lstatSync, readdirSync, watch, type FSWatcher } from 'node:fs';
+import { join, relative, resolve, isAbsolute } 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 { ASTParserEngine } from '../core/parser/tree-sitter.ts';
+import { shouldIgnoreSourcePath } from '../core/resources/ignore.ts';
+import { RESOURCE_LIMITS } from '../core/resources/limits.ts';
+import { SerialWorkQueue } from '../core/resources/work-queue.ts';
+
+export class WatchBudget {
+  count = 0;
+  constructor(private readonly limit = RESOURCE_LIMITS.watches) {}
+  take(): boolean { if (this.count >= this.limit) return false; this.count++; return true; }
+  release(): void { this.count--; }
+}
+
+export class WorkspaceWatcher {
+  private watches = new Map<string, FSWatcher>();
+  private pending = new Set<string>();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private poll: ReturnType<typeof setInterval> | null = null;
+  private flushing: Promise<void> | null = null;
+  private closed = false;
+  private reconcile = false;
+  private lastVerify = 0;
+  private abort = new AbortController();
+  private closing: Promise<void> | null = null;
+  private config: ValidatedSeptumConfig;
+  mode: 'native' | 'polling' = 'native';
+
+  constructor(
+    private readonly root: string,
+    private readonly repo: SeptumRepository,
+    private readonly pipeline: IngestionPipeline,
+    private readonly ready: Promise<void>,
+    private readonly queue: SerialWorkQueue,
+    private readonly budget: WatchBudget,
+    private readonly loadConfig: () => ValidatedSeptumConfig,
+  ) {
+    this.config = this.loadConfig();
+    this.registerDirectories();
+    // Periodic content verification also protects native watchers from missed events.
+    this.poll = setInterval(() => { void this.flush(false).catch(error => this.recordError(error)); }, RESOURCE_LIMITS.pollMs);
+    this.poll.unref();
+  }
+
+  get isBusy(): boolean { return this.flushing !== null; }
+  get pendingCount(): number { return this.pending.size; }
+  get watchCount(): number { return this.watches.size; }
+
+  private recordError(error: unknown): void {
+    if (!this.closed) this.repo.setMeta('sync_error', String(error));
+  }
+
+  private clearWatches(): void {
+    for (const watcher of this.watches.values()) { watcher.close(); this.budget.release(); }
+    this.watches.clear();
+  }
+
+  private fallback(error: unknown): void {
+    this.clearWatches();
+    this.mode = 'polling';
+    this.repo.setMeta('watcher_mode', 'polling');
+    console.error(`[Septum Watcher Warning] Using bounded polling: ${String(error)}`);
+  }
+
+  private registerDirectories(): void {
+    if (this.closed || this.mode === 'polling') return;
+    const config = this.loadConfig();
+    this.config = config;
+    const seen = new Set<string>();
+    const stack = [this.root];
+    const domainRoots = Object.values(config.domains || {})
+      .map(d => relative(this.root, resolve(this.root, d.root)).replace(/\\/g, '/').replace(/^\/|\/$/g, ''))
+      .filter(dr => dr !== '.' && dr !== '');
+    try {
+      while (stack.length) {
+        const dir = stack.pop()!;
+        const rel = relative(this.root, dir).replace(/\\/g, '/');
+        if (rel && shouldIgnoreSourcePath(rel, config.settings.ignore_patterns)) continue;
+        const stat = lstatSync(dir);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
+        seen.add(dir);
+        if (!this.watches.has(dir)) {
+          if (!this.budget.take()) throw new Error(`Native watch limit ${RESOURCE_LIMITS.watches} reached`);
+          let watcher: FSWatcher;
+          try {
+            watcher = watch(dir, {recursive: false}, (_event, filename) => {
+              if (filename) this.notify(relative(this.root, join(dir, String(filename))).replace(/\\/g, '/'));
+              else { this.reconcile = true; this.schedule(); }
+            });
+          } catch (error) { this.budget.release(); throw error; }
+          this.watches.set(dir, watcher);
+          watcher.on('error', error => { if (!this.closed) { this.fallback(error); this.reconcile = true; this.schedule(); } });
+        }
+        for (const entry of readdirSync(dir, {withFileTypes: true})) {
+          if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            const childDir = join(dir, entry.name);
+            const childRel = relative(this.root, childDir).replace(/\\/g, '/');
+            if (shouldIgnoreSourcePath(childRel, config.settings.ignore_patterns)) continue;
+            if (domainRoots.length > 0) {
+              const isRelevant = domainRoots.some(dr => childRel === dr || childRel.startsWith(dr + '/') || dr.startsWith(childRel + '/'));
+              if (!isRelevant) continue;
+            }
+            stack.push(childDir);
+          }
+        }
+      }
+      for (const [dir, watcher] of this.watches) {
+        if (!seen.has(dir)) { watcher.close(); this.watches.delete(dir); this.budget.release(); }
+      }
+      this.repo.setMeta('watcher_mode', 'native');
+    } catch (error) { this.fallback(error); }
+  }
+
+  notify(filename: string): void {
+    if (this.closed || this.reconcile) return;
+    const norm = filename.replace(/\\/g, '/');
+    const target = resolve(this.root, norm);
+    const rel = relative(this.root, target);
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('../') || shouldIgnoreSourcePath(norm, this.config.settings.ignore_patterns)) return;
+    let directory = this.watches.has(target);
+    try { directory ||= lstatSync(target).isDirectory(); } catch { /* deletion */ }
+    if (directory || /(^|\/)(package\.json|composer\.json|nest-cli\.json|go\.mod|tsconfig\.json|artisan)$/.test(norm)) {
+      this.reconcile = true;
+      this.pending.clear();
+    } else if (ASTParserEngine.isSourceFile(norm)) {
+      if (this.pending.size >= RESOURCE_LIMITS.pendingPaths) { this.reconcile = true; this.pending.clear(); }
+      else this.pending.add(norm);
+    } else return;
+    this.schedule();
+  }
+
+  private schedule(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => { this.timer = null; void this.flush(false).catch(error => this.recordError(error)); }, RESOURCE_LIMITS.debounceMs);
+  }
+
+  async flush(forceVerify = true, signal?: AbortSignal): Promise<void> {
+    if (this.closed) return;
+    signal?.throwIfAborted();
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    if (this.flushing) {
+      await this.flushing;
+      signal?.throwIfAborted();
+      if (forceVerify || this.pending.size || this.reconcile) return this.flush(forceVerify, signal);
+      return;
+    }
+    // SV-07: forceVerify forces verification in both native and polling modes
+    const verify = forceVerify || this.mode === 'polling' || Date.now() - this.lastVerify >= RESOURCE_LIMITS.verifyMs;
+    const poll = this.mode === 'polling';
+    if (!poll && !verify && !this.reconcile && !this.pending.size && !this.repo.getMeta('sync_error')) return;
+    this.flushing = this.queue.run(async () => {
+      await this.ready;
+      signal?.throwIfAborted();
+      this.abort.signal.throwIfAborted();
+      const config = this.loadConfig();
+      if (poll || verify || this.reconcile || this.repo.getMeta('sync_error')) {
+        this.reconcile = false;
+        this.pending.clear();
+        await this.pipeline.run(config, {verifyContent: verify, signal: this.abort.signal});
+        if (verify) this.lastVerify = Date.now();
+        this.registerDirectories();
+      }
+      let sourceEvents = false;
+      while (this.pending.size) {
+        sourceEvents = true;
+        const paths = [...this.pending]; this.pending.clear();
+        for (const filename of paths) {
+          signal?.throwIfAborted();
+          this.abort.signal.throwIfAborted();
+          const target = resolve(this.root, filename);
+          if (existsSync(target)) await this.pipeline.ingestFile(target, config);
+          else this.repo.runInTransaction(() => {
+            this.repo.deleteFileByPath(filename); this.repo.clearVerticalSlices(); this.repo.setMeta('slices_dirty', '1');
+            const unsupported: string[] = JSON.parse(this.repo.getMeta('unsupported_files') || '[]');
+            this.repo.setMeta('unsupported_files', JSON.stringify(unsupported.filter(path => path !== filename)));
+            const skipped: {path: string; reason: string}[] = JSON.parse(this.repo.getMeta('skipped_files') || '[]');
+            this.repo.setMeta('skipped_files', JSON.stringify(skipped.filter(file => file.path !== filename)));
+          });
+        }
+      }
+      if (sourceEvents || this.repo.getMeta('slices_dirty') === '1') await this.pipeline.run(config, {signal: this.abort.signal});
+    }, signal);
+    try { await this.flushing; }
+    finally { this.flushing = null; }
+    // A directory event during sync must not be lost behind the coalesced flush.
+    if (!this.closed && (this.reconcile || this.pending.size)) await this.flush(false);
+  }
+
+  close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true;
+    this.abort.abort();
+    if (this.timer) clearTimeout(this.timer);
+    if (this.poll) clearInterval(this.poll);
+    this.clearWatches(); this.pending.clear();
+    this.closing = Promise.allSettled([this.ready, this.flushing]).then(() => {});
+    return this.closing;
+  }
+}

package/src/types/index.ts

@@ -358,6 +358,7 @@ export interface GetSymbolDetailsResponse {
 }
 
 export interface GetSymbolImpactArgs {
+  domain?: string;
   symbol: string;
   query?: string;
   workspace_path?: string;

package/src/cli/commands/ingest.ts

@@ -1,29 +0,0 @@
-import { ConfigLoader } from "../../core/config/loader.ts";
-import { SeptumDatabase } from "../../core/database/client.ts";
-import { SeptumRepository } from "../../core/database/repository.ts";
-import { IngestionPipeline } from "../../core/ingestion/pipeline.ts";
-
-export async function handleIngestCommand(): Promise<void> {
-  console.log("[Septum] Starting codebase structural ingestion...");
-
-  const config = ConfigLoader.load();
-  const db = new SeptumDatabase(config.settings.db_path);
-  const repo = new SeptumRepository(db.raw);
-  const pipeline = new IngestionPipeline(repo);
-
-  const metrics = await pipeline.run(config);
-
-  console.log("=========================================");
-  console.log("  Septum Ingestion Complete");
-  console.log("=========================================");
-  console.log(`  Domains Processed:     ${metrics.domains_processed}`);
-  console.log(`  Files Scanned:         ${metrics.files_scanned}`);
-  console.log(`  Files Updated/Added:   ${metrics.files_updated}`);
-  console.log(`  Files Cached/Skipped:  ${metrics.files_skipped}`);
-  console.log(`  Symbols Indexed:       ${metrics.symbols_indexed}`);
-  console.log(`  Dependencies Indexed:  ${metrics.dependencies_indexed}`);
-  console.log(`  Execution Time:        ${metrics.duration_ms} ms`);
-  console.log("=========================================");
-
-  db.close();
-}

package/src/cli/commands/locate.ts

@@ -1,61 +0,0 @@
-import { ConfigLoader } from "../../core/config/loader.ts";
-import { SeptumDatabase } from "../../core/database/client.ts";
-import { SeptumRepository } from "../../core/database/repository.ts";
-import { SymbolLocator } from "../../core/resolver/symbol-locator.ts";
-
-export async function handleLocateCommand(
-  query: string,
-  options?: { domain?: string; json?: boolean }
-): Promise<void> {
-  const config = ConfigLoader.load();
-  const db = new SeptumDatabase(config.settings.db_path);
-  const repo = new SeptumRepository(db.raw);
-
-  try {
-    const locator = new SymbolLocator(repo);
-    const result = locator.locate(query, options?.domain);
-
-    if (options?.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    if (result.found) {
-      console.log(`\n✅ Symbol Found:`);
-      console.log(`   File:      ${result.file_path}`);
-      if (result.exact_symbol) {
-        console.log(`   Symbol:    ${result.exact_symbol.name} [${result.exact_symbol.kind}]`);
-        console.log(`   Signature: ${result.exact_symbol.signature}`);
-        console.log(`   Lines:     ${result.exact_symbol.line_start} - ${result.exact_symbol.line_end}`);
-      }
-      if (result.sibling_methods && result.sibling_methods.length > 0) {
-        console.log(`\n   Available Methods in Container:`);
-        console.log(`   ${result.sibling_methods.join(", ")}`);
-      }
-    } else {
-      console.log(`\n❌ Diagnostic Result:`);
-      if (result.file_path) {
-        console.log(`   File:      ${result.file_path}`);
-        console.log(`   Container: ${result.container_name}`);
-      }
-      console.log(`   Message:   ${result.message}`);
-
-      if (result.sibling_methods && result.sibling_methods.length > 0) {
-        console.log(`\n   Available Methods:`);
-        console.log(`   ${result.sibling_methods.join(", ")}`);
-      }
-
-      if (result.suggestions.length > 0) {
-        console.log(`\n   Suggestions (Ranked by Match):`);
-        for (const sug of result.suggestions) {
-          const matchPercent = Math.round(sug.similarity_score * 100);
-          console.log(
-            `   • ${sug.name} (${matchPercent}% match) [line ${sug.line_start}] -> ${sug.signature}`
-          );
-        }
-      }
-    }
-  } finally {
-    db.close();
-  }
-}

package/src/cli/commands/query.ts

@@ -1,104 +0,0 @@
-import { ConfigLoader } from "../../core/config/loader.ts";
-import { SeptumDatabase } from "../../core/database/client.ts";
-import { SeptumRepository } from "../../core/database/repository.ts";
-import type { DomainCatalogResponse } from "../../types/index.ts";
-
-export interface QueryCommandOptions {
-  json?: boolean;
-  full?: boolean;
-  file?: string;
-}
-
-export async function handleQueryCommand(
-  domainName?: string,
-  archetype?: string,
-  jsonOutputOrOptions?: boolean | QueryCommandOptions,
-  extraOptions?: QueryCommandOptions
-): Promise<void> {
-  const options: QueryCommandOptions =
-    typeof jsonOutputOrOptions === "boolean"
-      ? { json: jsonOutputOrOptions, ...extraOptions }
-      : { ...jsonOutputOrOptions, ...extraOptions };
-
-  const jsonOutput = Boolean(options.json);
-  const detailLevel: "compact" | "full" = options.full ? "full" : "compact";
-  const fileFilter = options.file;
-
-  const config = ConfigLoader.load();
-  const db = new SeptumDatabase(config.settings.db_path);
-  const repo = new SeptumRepository(db.raw);
-
-  if (!domainName) {
-    const allDomains = repo.getAllDomains();
-    if (allDomains.length === 0) {
-      console.log("[Septum] No domains found in database. Run 'septum ingest' first.");
-      db.close();
-      return;
-    }
-
-    console.log("=== Registered Domains in Septum ===");
-    for (const d of allDomains) {
-      console.log(`- ${d.name} (root: ${d.root_path})`);
-    }
-    db.close();
-    return;
-  }
-
-  const catalog: DomainCatalogResponse | null = (repo.getDomainCatalog as any)(
-    domainName,
-    archetype,
-    { detailLevel, fileFilter }
-  );
-  if (!catalog) {
-    console.error(`[Septum Error] Domain '${domainName}' not found in database. Run 'septum ingest' first.`);
-    db.close();
-    process.exit(1);
-  }
-
-  if (jsonOutput) {
-    console.log(JSON.stringify(catalog, null, 2));
-  } else {
-    console.log(`=================================================`);
-    console.log(`  Domain: ${catalog.domain.toUpperCase()} (Root: ${catalog.root})`);
-    console.log(`=================================================`);
-    console.log(`  Detail Level:            ${catalog.detail_level ?? detailLevel}`);
-    console.log(`  Allowed Dependencies:    [${catalog.allowed_dependencies.join(", ")}]`);
-    console.log(`  Forbidden Dependencies:  [${catalog.forbidden_dependencies.join(", ")}]`);
-    console.log(`  Total Files Cataloged:   ${catalog.total_files ?? catalog.files.length} (Showing: ${catalog.showing_files ?? catalog.files.length})`);
-    console.log(`-------------------------------------------------`);
-
-    for (const file of catalog.files) {
-      const lineInfo = file.line_count ? `, ${file.line_count} lines` : "";
-      console.log(`\n  File: ${file.path} [archetype: ${file.archetype}${lineInfo}]`);
-      if (file.connections) {
-        const importsStr = file.connections.imports_from.length > 0 ? file.connections.imports_from.join(", ") : "none";
-        console.log(`    ↔ Connections: imports [${importsStr}] | imported by ${file.connections.imported_by_count} file(s)`);
-      }
-      for (const sym of file.symbols) {
-        const spanStr = sym.line_span ? ` (L${sym.line_span})` : "";
-        const countsStr =
-          sym.methods_count !== undefined
-            ? ` [${sym.methods_count} methods${sym.properties_count ? `, ${sym.properties_count} props` : ""}]`
-            : "";
-        console.log(`    • ${sym.kind.toUpperCase()} ${sym.name}${spanStr}${countsStr}`);
-        if (sym.methods && sym.methods.length > 0) {
-          for (const m of sym.methods) {
-            console.log(`        - ${m}`);
-          }
-        }
-        if (sym.signatures && sym.signatures.length > 0) {
-          for (const s of sym.signatures) {
-            console.log(`        - ${s}`);
-          }
-        }
-      }
-    }
-    if (catalog.agent_hint) {
-      console.log(`\n  💡 ${catalog.agent_hint}`);
-    }
-    console.log(`\n=================================================`);
-  }
-
-  db.close();
-}
-