septum 0.1.0

package/src/cli/commands/init.ts

@@ -0,0 +1,211 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { handleIngestCommand } from "./ingest.ts";
+import {
+  SEPTUM_HOOKS_CONFIG,
+  SEPTUM_POST_WRITE_SCRIPT,
+  SEPTUM_PRE_WRITE_SCRIPT,
+} from "../templates/hooks.ts";
+import { SEPTUM_RULES_TEMPLATE } from "../templates/rules.ts";
+import { SEPTUM_MAP_SKILL_TEMPLATE } from "../templates/skill.ts";
+import { TopologyDetector } from "../../core/discovery/topology-detector.ts";
+import { SeptumDatabase } from "../../core/database/client.ts";
+import { SeptumRepository } from "../../core/database/repository.ts";
+
+export async function handleInitCommand(force: boolean = false): Promise<void> {
+  console.log("[Septum] Initializing Septum bounded-context environment (Zero-Config)...\n");
+
+  const cwd = process.cwd();
+  const dbPath = ".septum/septum.db";
+
+  // 1. Auto-discover project topology and persist to SQLite SSOT
+  console.log("  • Analyzing codebase topology and modular boundaries...");
+  const db = new SeptumDatabase(dbPath);
+  const repo = new SeptumRepository(db.raw);
+  const domains = TopologyDetector.discoverAndPersist(repo, cwd);
+  const domainNames = Object.keys(domains);
+  console.log(`  ✓ Discovered and registered ${domainNames.length} domains directly in SQLite (${dbPath}):`);
+  for (const name of domainNames) {
+    console.log(`    - ${name}: root -> '${domains[name].root}'`);
+  }
+  db.close();
+
+  // 2. Ensure .gitignore excludes local SQLite cache
+  ensureGitIgnore(cwd);
+
+  // 3. Install Git Pre-Commit Hook
+  installGitHook(cwd);
+
+  // 4. Scaffold Agent Customizations (.agents/skills, .agents/hooks, .agents/rules)
+  scaffoldAgentCustomizations(cwd);
+
+  // 5. Run initial codebase ingestion
+  console.log("\n[Septum] Running initial ingestion to build deterministic structural catalog...");
+  try {
+    await handleIngestCommand();
+    console.log("\n✓ Septum successfully initialized and ready for production use!");
+    console.log("  • Pre-commit hook is active (runs 'septum check --staged' before each commit).");
+    console.log("  • AI Agent skill '/septum-map' and boundary hooks installed in '.agents/'.");
+    console.log("  • MCP server is ready for AI coding agents via 'septum serve'.\n");
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`\n[Septum Warning] Initial ingestion encountered an error: ${message}`);
+    console.warn("Run 'septum ingest' manually to retry.");
+  }
+}
+
+function ensureGitIgnore(cwd: string): void {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  const entriesToEnsure = [".septum/*.db*", ".septum/"];
+
+  if (fs.existsSync(gitignorePath)) {
+    let content = fs.readFileSync(gitignorePath, "utf-8");
+    const missing = entriesToEnsure.filter((entry) => !content.includes(entry));
+
+    if (missing.length > 0) {
+      const addition = `\n# Septum local database and cache\n${missing.join("\n")}\n`;
+      fs.appendFileSync(gitignorePath, addition, "utf-8");
+      console.log("  ✓ Updated .gitignore to exclude local SQLite cache (.septum/).");
+    } else {
+      console.log("  ✓ .gitignore already configured for Septum.");
+    }
+  } else {
+    fs.writeFileSync(
+      gitignorePath,
+      `# Septum local database and cache\n${entriesToEnsure.join("\n")}\n`,
+      "utf-8"
+    );
+    console.log("  ✓ Created .gitignore excluding local SQLite cache (.septum/).");
+  }
+}
+
+function installGitHook(cwd: string): void {
+  const gitDir = path.join(cwd, ".git");
+  if (!fs.existsSync(gitDir)) {
+    console.log("  ⚠ No .git directory found. Skipping pre-commit hook installation.");
+    return;
+  }
+
+  const huskyDir = path.join(cwd, ".husky");
+  if (fs.existsSync(huskyDir)) {
+    const huskyPreCommit = path.join(huskyDir, "pre-commit");
+    const hookCommand = "[ -f ./bin/septum.ts ] && bun run ./bin/septum.ts check --staged || command -v septum >/dev/null 2>&1 && septum check --staged || [ -f ./node_modules/.bin/septum ] && ./node_modules/.bin/septum check --staged || bunx septum check --staged";
+    if (fs.existsSync(huskyPreCommit)) {
+      const existing = fs.readFileSync(huskyPreCommit, "utf-8");
+      if (!existing.includes("septum check")) {
+        fs.appendFileSync(huskyPreCommit, `\n${hookCommand}\n`, "utf-8");
+      }
+    } else {
+      fs.writeFileSync(huskyPreCommit, `#!/usr/bin/env sh\n${hookCommand}\n`, "utf-8");
+      try {
+        fs.chmodSync(huskyPreCommit, 0o755);
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`  Notice: Could not set executable permission on '${huskyPreCommit}': ${message}`);
+      }
+    }
+    console.log("  ✓ Installed pre-commit hook in .husky/pre-commit.");
+    return;
+  }
+
+  const hooksDir = path.join(gitDir, "hooks");
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const preCommitHook = path.join(hooksDir, "pre-commit");
+  const hookScript = `#!/usr/bin/env sh
+# Septum deterministic boundary pre-commit hook
+echo "[Septum Hook] Auditing staged changes against domain boundaries..."
+
+if command -v bun >/dev/null 2>&1 && [ -f "./bin/septum.ts" ]; then
+  bun run ./bin/septum.ts check --staged
+elif command -v septum >/dev/null 2>&1; then
+  septum check --staged
+elif [ -f "./node_modules/.bin/septum" ]; then
+  ./node_modules/.bin/septum check --staged
+elif command -v bunx >/dev/null 2>&1; then
+  bunx septum check --staged
+else
+  echo "[Septum Hook] Notice: Septum executable not found. Skipping boundary check."
+fi
+`;
+
+  fs.writeFileSync(preCommitHook, hookScript, "utf-8");
+  try {
+    fs.chmodSync(preCommitHook, 0o755);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`  Notice: Could not set executable permission on '${preCommitHook}': ${message}`);
+  }
+  console.log("  ✓ Installed executable git pre-commit hook at '.git/hooks/pre-commit'.");
+}
+
+function scaffoldAgentCustomizations(cwd: string): void {
+  const agentsDir = path.join(cwd, ".agents");
+
+  // 1. Skill: .agents/skills/septum-map/SKILL.md
+  const skillDir = path.join(agentsDir, "skills", "septum-map");
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+  const skillPath = path.join(skillDir, "SKILL.md");
+  fs.writeFileSync(skillPath, SEPTUM_MAP_SKILL_TEMPLATE, "utf-8");
+  console.log("  ✓ Deployed AI Agent skill: '.agents/skills/septum-map/SKILL.md'.");
+
+  // 2. Rule: .agents/rules/septum-boundary.md
+  const rulesDir = path.join(agentsDir, "rules");
+  if (!fs.existsSync(rulesDir)) {
+    fs.mkdirSync(rulesDir, { recursive: true });
+  }
+  const rulePath = path.join(rulesDir, "septum-boundary.md");
+  fs.writeFileSync(rulePath, SEPTUM_RULES_TEMPLATE, "utf-8");
+  console.log("  ✓ Deployed AI Agent boundary rules: '.agents/rules/septum-boundary.md'.");
+
+  // 3. Hook Script: .agents/hooks/septum-pre-write.sh
+  const hooksDir = path.join(agentsDir, "hooks");
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+  const preWriteHook = path.join(hooksDir, "septum-pre-write.sh");
+  fs.writeFileSync(preWriteHook, SEPTUM_PRE_WRITE_SCRIPT, "utf-8");
+  try {
+    fs.chmodSync(preWriteHook, 0o755);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`  Notice: Could not set executable permission on '${preWriteHook}': ${message}`);
+  }
+  console.log("  ✓ Deployed pre-write hook script: '.agents/hooks/septum-pre-write.sh'.");
+
+  // 3b. Post-Write Hook Script: .agents/hooks/septum-post-write.sh
+  const postWriteHook = path.join(hooksDir, "septum-post-write.sh");
+  fs.writeFileSync(postWriteHook, SEPTUM_POST_WRITE_SCRIPT, "utf-8");
+  try {
+    fs.chmodSync(postWriteHook, 0o755);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`  Notice: Could not set executable permission on '${postWriteHook}': ${message}`);
+  }
+  console.log("  ✓ Deployed post-write hook script: '.agents/hooks/septum-post-write.sh'.");
+
+  // 4. Hooks Config: .agents/hooks.json
+  const hooksJsonPath = path.join(agentsDir, "hooks.json");
+  let existingHooks: Record<string, unknown> = {};
+
+  if (fs.existsSync(hooksJsonPath)) {
+    try {
+      const raw = fs.readFileSync(hooksJsonPath, "utf-8");
+      existingHooks = JSON.parse(raw);
+    } catch {
+      // Malformed JSON fallback
+    }
+  }
+
+  const mergedHooks = {
+    ...existingHooks,
+    ...SEPTUM_HOOKS_CONFIG,
+  };
+
+  fs.writeFileSync(hooksJsonPath, JSON.stringify(mergedHooks, null, 2) + "\n", "utf-8");
+  console.log("  ✓ Configured AI Agent lifecycle hooks: '.agents/hooks.json'.");
+}

package/src/cli/commands/locate.ts

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,64 @@
+import { ConfigLoader } from "../../core/config/loader.ts";
+import { SeptumDatabase } from "../../core/database/client.ts";
+import { SeptumRepository } from "../../core/database/repository.ts";
+
+export async function handleQueryCommand(domainName?: string, archetype?: string, jsonOutput?: boolean): Promise<void> {
+  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 = repo.getDomainCatalog(domainName, archetype);
+  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(`  Allowed Dependencies:    [${catalog.allowed_dependencies.join(", ")}]`);
+    console.log(`  Forbidden Dependencies:  [${catalog.forbidden_dependencies.join(", ")}]`);
+    console.log(`  Total Files Cataloged:   ${catalog.files.length}`);
+    console.log(`-------------------------------------------------`);
+
+    for (const file of catalog.files) {
+      console.log(`\n  File: ${file.path} [archetype: ${file.archetype}]`);
+      for (const sym of file.symbols) {
+        console.log(`    • ${sym.kind.toUpperCase()} ${sym.name}`);
+        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}`);
+          }
+        }
+      }
+    }
+    console.log(`\n=================================================`);
+  }
+
+  db.close();
+}

package/src/cli/commands/serve.ts

@@ -0,0 +1,5 @@
+import { runMCPServer } from "../../mcp/server.ts";
+
+export async function handleServeCommand(): Promise<void> {
+  await runMCPServer();
+}

package/src/cli/commands/slice.ts

@@ -0,0 +1,90 @@
+import { ConfigLoader } from "../../core/config/loader.ts";
+import { SeptumDatabase } from "../../core/database/client.ts";
+import { SeptumRepository } from "../../core/database/repository.ts";
+import { VerticalSliceTracer } from "../../core/resolver/vertical-slice-tracer.ts";
+
+export async function handleSliceCommand(
+  query: string,
+  options?: { json?: boolean }
+): Promise<void> {
+  const config = ConfigLoader.load();
+  const db = new SeptumDatabase(config.settings.db_path);
+  const repo = new SeptumRepository(db.raw);
+
+  try {
+    const tracer = new VerticalSliceTracer(repo);
+    const result = tracer.trace(query);
+
+    if (options?.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.found && result.slice) {
+      const s = result.slice;
+      console.log(`\n=================================================`);
+      console.log(`  VERTICAL SLICE: ${s.route.method} ${s.route.uri}`);
+      console.log(`=================================================`);
+      if (s.route.name) {
+        console.log(`  • Route Name:   ${s.route.name}`);
+      }
+
+      if (s.request) {
+        console.log(`\n  • Request Validation:`);
+        console.log(`      Class: ${s.request.class} (${s.request.file || "inline"})`);
+        const rules = Object.keys(s.request.rules);
+        if (rules.length > 0) {
+          console.log(`      Rules:`);
+          for (const r of rules) {
+            console.log(`        - ${r}: ${s.request.rules[r]}`);
+          }
+        }
+      }
+
+      console.log(`\n  • Controller Action:`);
+      console.log(`      Class:  ${s.controller.class}@${s.controller.action}`);
+      console.log(`      Target: ${s.controller.file || "unknown"}:${s.controller.line}`);
+
+      if (s.model) {
+        console.log(`\n  • Model:`);
+        console.log(`      Class:    ${s.model.class} (${s.model.file || "unknown"})`);
+        if (s.model.fillable && s.model.fillable.length > 0) {
+          console.log(`      Fillable: [${s.model.fillable.join(", ")}]`);
+        }
+        if (s.model.casts && Object.keys(s.model.casts).length > 0) {
+          console.log(`      Casts:    ${JSON.stringify(s.model.casts)}`);
+        }
+      }
+
+      if (s.frontend) {
+        console.log(`\n  • Frontend Target:`);
+        console.log(`      Page:  ${s.frontend.target}`);
+        if (s.frontend.props.length > 0) {
+          console.log(`      Props: [${s.frontend.props.join(", ")}]`);
+        }
+      }
+
+      if (result.alternatives && result.alternatives.length > 0) {
+        console.log(`\n  • Alternative Matches:`);
+        for (const alt of result.alternatives) {
+          console.log(`      - ${alt.method} ${alt.uri} -> ${alt.controller}@${alt.action}`);
+        }
+      }
+      console.log(`\n=================================================\n`);
+    } else {
+      console.log(`\n❌ Vertical Slice Not Found:`);
+      console.log(`   Query:   ${result.query}`);
+      console.log(`   Message: ${result.message}`);
+
+      if (result.alternatives && result.alternatives.length > 0) {
+        console.log(`\n   Available Slices:`);
+        for (const alt of result.alternatives) {
+          console.log(`      - ${alt.method} ${alt.uri} -> ${alt.controller}@${alt.action}`);
+        }
+      }
+      console.log(``);
+    }
+  } finally {
+    db.close();
+  }
+}

package/src/cli/commands/sync.ts

@@ -0,0 +1,31 @@
+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 interface SyncCommandOptions {
+  json?: boolean;
+}
+
+export async function handleSyncCommand(options: SyncCommandOptions = {}): Promise<void> {
+  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);
+
+  if (options.json) {
+    console.log(JSON.stringify(metrics, null, 2));
+  } else {
+    console.log(
+      `[Septum Sync] Ingested in ${metrics.duration_ms.toFixed(0)}ms: ` +
+        `${metrics.files_updated} updated/added, ` +
+        `${metrics.files_skipped} unchanged, ` +
+        `${metrics.symbols_indexed} symbols, ` +
+        `${metrics.dependencies_indexed} deps.`
+    );
+  }
+
+  db.close();
+}

package/src/cli/index.ts

@@ -0,0 +1,178 @@
+import { SessionManager } from "../core/session/session-manager.ts";
+import { handleCheckCommand } from "./commands/check.ts";
+import { handleHookCommand } from "./commands/hook.ts";
+import { handleIngestCommand } from "./commands/ingest.ts";
+import { handleInitCommand } from "./commands/init.ts";
+import { handleLocateCommand } from "./commands/locate.ts";
+import { handleQueryCommand } from "./commands/query.ts";
+import { handleServeCommand } from "./commands/serve.ts";
+import { handleSliceCommand } from "./commands/slice.ts";
+import { handleSyncCommand } from "./commands/sync.ts";
+
+export async function runCLI(argv: string[]): Promise<void> {
+  const args = argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    printHelp();
+    return;
+  }
+
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log("Septum v0.1.0");
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "init": {
+        const force = args.includes("--force") || args.includes("-f");
+        await handleInitCommand(force);
+        break;
+      }
+
+      case "ingest": {
+        await handleIngestCommand();
+        break;
+      }
+
+      case "sync": {
+        const json = args.includes("--json");
+        await handleSyncCommand({ json });
+        break;
+      }
+
+      case "query": {
+        const domainName = args[1] && !args[1].startsWith("-") ? args[1] : undefined;
+        let archetype: string | undefined;
+        const archIndex = args.indexOf("--archetype");
+        if (archIndex !== -1 && args[archIndex + 1]) {
+          archetype = args[archIndex + 1];
+        }
+        const jsonOutput = args.includes("--json");
+        await handleQueryCommand(domainName, archetype, jsonOutput);
+        break;
+      }
+
+      case "locate": {
+        const query = args[1];
+        if (!query) {
+          console.error("Usage: septum locate <symbol-or-error> [--domain <domain>] [--json]");
+          process.exit(1);
+        }
+        let domain: string | undefined;
+        const domIndex = args.indexOf("--domain");
+        if (domIndex !== -1 && args[domIndex + 1]) {
+          domain = args[domIndex + 1];
+        }
+        const json = args.includes("--json");
+        await handleLocateCommand(query, { domain, json });
+        break;
+      }
+
+      case "slice": {
+        const query = args[1];
+        if (!query) {
+          console.error("Usage: septum slice <route-or-intent> [--json]");
+          process.exit(1);
+        }
+        const json = args.includes("--json");
+        await handleSliceCommand(query, { json });
+        break;
+      }
+
+      case "check": {
+        const strict = args.includes("--strict");
+        const staged = args.includes("--staged");
+        let feature: string | undefined;
+        const featIndex = args.indexOf("--feature");
+        if (featIndex !== -1 && args[featIndex + 1]) {
+          feature = args[featIndex + 1];
+        }
+        await handleCheckCommand({ strict, staged, feature });
+        break;
+      }
+
+      case "serve": {
+        await handleServeCommand();
+        break;
+      }
+
+      case "feature": {
+        const sub = args[1];
+        if (sub === "clear") {
+          const cleared = SessionManager.clearActiveSession(process.cwd());
+          if (cleared) {
+            console.log("✓ Active feature session successfully cleared.");
+          } else {
+            console.log("ℹ No active feature session found.");
+          }
+        } else if (sub === "status" || !sub) {
+          const current = SessionManager.getActiveSession(process.cwd());
+          if (current) {
+            console.log(`\nActive Feature Session:`);
+            console.log(`▶ Feature Key : ${current.feature_key}`);
+            console.log(`▶ Domain      : ${current.domain}`);
+            console.log(`▶ Locked At   : ${current.locked_at}`);
+            console.log(`▶ Touchpoints : ${current.touchpoints.join(", ")}\n`);
+          } else {
+            console.log("ℹ No active feature session. All domain files accessible according to boundary rules.");
+          }
+        } else {
+          console.error(`Unknown feature subcommand: '${sub}'. Use 'status' or 'clear'.`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case "hook": {
+        await handleHookCommand(args);
+        break;
+      }
+
+      default: {
+        console.error(`[Septum] Unknown command: '${command}'`);
+        console.error("Run 'septum --help' for available commands.");
+        process.exit(1);
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m[Septum Error]\x1b[0m ${message}`);
+    process.exit(1);
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+Septum — Deterministic Bounded-Context & Structural File Catalog
+Version: 0.1.0
+
+USAGE:
+  septum <command> [options]
+
+COMMANDS:
+  init                  Initialize configuration, gitignore, pre-commit hook, and ingest catalog
+                        Options:
+                          --force, -f           Overwrite existing catalog and configuration
+  ingest                Scan codebase, parse AST, and synchronize .septum/septum.db
+  sync                  Fast incremental synchronization of changed files to SQLite SSOT
+                        Options:
+                          --json                Output formatted JSON metrics
+  query [domain]        Query structural catalog for a domain or list all domains
+                        Options:
+                          --archetype <name>    Filter by archetype (service, model, controller)
+                          --json                Output formatted JSON
+  check                 Audit codebase for cross-domain boundary violations
+                        Options:
+                          --staged              Audit only git staged changes (ideal for pre-commit)
+                          --feature <name>      Enforce feature-specific allowed_touchpoints
+                          --strict              Exit with code 1 on any violation
+  feature [status|clear] View or release active feature context session lock
+  serve                 Start Model Context Protocol (MCP) server over stdio
+
+FLAGS:
+  -h, --help            Show this help message
+  -v, --version         Show current version
+`);
+}