septum 0.1.0 → 0.1.2

package/src/cli/index.ts

@@ -1,178 +1,199 @@
-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
-`);
-}
+import { parseArgs } from "node:util";
+import { SessionManager } from "../core/session/session-manager.ts";
+import { SEPTUM_VERSION } from "../version.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> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv.slice(2),
+      options: {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        force: { type: "boolean", short: "f" },
+        json: { type: "boolean" },
+        strict: { type: "boolean" },
+        staged: { type: "boolean" },
+        domain: { type: "string", short: "d" },
+        archetype: { type: "string", short: "a" },
+        feature: { type: "string" },
+      },
+      allowPositionals: true,
+      strict: false,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m[Septum Error]\x1b[0m ${message}`);
+    process.exit(1);
+  }
+
+  const { values: flags, positionals } = parsed;
+  const command = positionals[0];
+
+  if (flags.version || command === "version") {
+    console.log(`Septum v${SEPTUM_VERSION}`);
+    return;
+  }
+
+  if (flags.help || !command || command === "help") {
+    printHelp();
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "init": {
+        const force = Boolean(flags.force);
+        await handleInitCommand(force);
+        break;
+      }
+
+      case "ingest": {
+        await handleIngestCommand();
+        break;
+      }
+
+      case "sync": {
+        const json = Boolean(flags.json);
+        await handleSyncCommand({ json });
+        break;
+      }
+
+      case "query": {
+        const domainName = positionals[1];
+        const archetype = typeof flags.archetype === "string" ? flags.archetype : undefined;
+        const jsonOutput = Boolean(flags.json);
+        await handleQueryCommand(domainName, archetype, jsonOutput);
+        break;
+      }
+
+      case "locate": {
+        const query = positionals[1];
+        if (!query) {
+          console.error("Usage: septum locate <symbol-or-error> [--domain <domain>] [--json]");
+          process.exit(1);
+        }
+        const domain = typeof flags.domain === "string" ? flags.domain : undefined;
+        const json = Boolean(flags.json);
+        await handleLocateCommand(query, { domain, json });
+        break;
+      }
+
+      case "slice": {
+        const query = positionals[1];
+        if (!query) {
+          console.error("Usage: septum slice <route-or-intent> [--json]");
+          process.exit(1);
+        }
+        const json = Boolean(flags.json);
+        await handleSliceCommand(query, { json });
+        break;
+      }
+
+      case "check": {
+        const strict = Boolean(flags.strict);
+        const staged = Boolean(flags.staged);
+        const feature = typeof flags.feature === "string" ? flags.feature : undefined;
+        await handleCheckCommand({ strict, staged, feature });
+        break;
+      }
+
+      case "serve": {
+        await handleServeCommand();
+        break;
+      }
+
+      case "feature": {
+        const sub = positionals[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(argv.slice(2));
+        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: v${SEPTUM_VERSION}
+
+USAGE:
+  septum <command> [options]
+  septum [flags]
+
+COMMANDS:
+  Catalog & Ingestion:
+    init                  Initialize configuration, gitignore, pre-commit hook, and catalog
+                          Flags: -f, --force
+    ingest                Full AST scan and synchronization to SQLite database
+    sync                  Incremental fast synchronization of modified files
+                          Flags: --json
+
+  Structural Discovery:
+    query [domain]        Query structural catalog for a domain or whole project
+                          Flags: -a, --archetype <name>, --json
+    locate <query>        Locate symbol, class, interface, method, or error source
+                          Flags: -d, --domain <name>, --json
+    slice <route|intent>  Trace end-to-end vertical execution slice for route/intent
+                          Flags: --json
+
+  Boundary & Enforcement:
+    check                 Audit codebase for cross-domain boundary violations
+                          Flags: --strict, --staged, --feature <name>
+    feature [status|clear] View or release active feature context session lock
+    hook [subhook]        Internal pre-tool guardrail hook (e.g. pre-write)
+
+  Daemon & Protocol:
+    serve                 Start Model Context Protocol (MCP) server over stdio
+
+GLOBAL FLAGS:
+  -h, --help              Show this help message
+  -v, --version           Show current version
+  --json                  Output formatted JSON metrics / results
+`);
+}

package/src/cli/templates/hooks.ts

@@ -1,75 +1,75 @@
-export const SEPTUM_HOOKS_CONFIG = {
-  "septum-boundary-guard": {
-    "PreToolUse": [
-      {
-        "matcher": "write_to_file|replace_file_content",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "sh -c 'HOOK=\"$(git rev-parse --show-toplevel 2>/dev/null)/.agents/hooks/septum-pre-write.sh\"; if [ -f \"$HOOK\" ]; then exec \"$HOOK\"; else exit 0; fi'",
-            "timeout": 10,
-          },
-        ],
-      },
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "write_to_file|replace_file_content",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "sh -c 'HOOK=\"$(git rev-parse --show-toplevel 2>/dev/null)/.agents/hooks/septum-post-write.sh\"; if [ -f \"$HOOK\" ]; then exec \"$HOOK\"; else exit 0; fi'",
-            "timeout": 15,
-          },
-        ],
-      },
-    ],
-  },
-};
-
-export const SEPTUM_PRE_WRITE_SCRIPT = `#!/usr/bin/env sh
-# Septum 3-Gate Boundary Guard Pre-Write Hook
-# Intercepts write_to_file and replace_file_content before disk mutation
-
-ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-if [ ! -f "$ROOT_DIR/.septum/septum.db" ]; then
-  exit 0
-fi
-
-# Delegate directly to Septum's active 3-gate hook engine
-if command -v bun >/dev/null 2>&1 && [ -f "$ROOT_DIR/bin/septum.ts" ]; then
-  exec bun run "$ROOT_DIR/bin/septum.ts" hook pre-write
-elif command -v septum >/dev/null 2>&1; then
-  exec septum hook pre-write
-elif [ -f "$ROOT_DIR/node_modules/.bin/septum" ]; then
-  exec "$ROOT_DIR/node_modules/.bin/septum" hook pre-write
-elif command -v bunx >/dev/null 2>&1; then
-  exec bunx septum hook pre-write
-fi
-
-exit 0
-`;
-
-export const SEPTUM_POST_WRITE_SCRIPT = `#!/usr/bin/env sh
-# Septum Automated Incremental Post-Write Hook
-# Syncs modified AST into SQLite SSOT after file mutations
-
-ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-if [ ! -f "$ROOT_DIR/.septum/septum.db" ]; then
-  exit 0
-fi
-
-# Trigger background incremental sync
-if command -v bun >/dev/null 2>&1 && [ -f "$ROOT_DIR/bin/septum.ts" ]; then
-  bun run "$ROOT_DIR/bin/septum.ts" sync --json >/dev/null 2>&1 &
-elif command -v septum >/dev/null 2>&1; then
-  septum sync --json >/dev/null 2>&1 &
-elif [ -f "$ROOT_DIR/node_modules/.bin/septum" ]; then
-  "$ROOT_DIR/node_modules/.bin/septum" sync --json >/dev/null 2>&1 &
-elif command -v bunx >/dev/null 2>&1; then
-  bunx septum sync --json >/dev/null 2>&1 &
-fi
-
-exit 0
-`;
-
+export const SEPTUM_HOOKS_CONFIG = {
+  "septum-boundary-guard": {
+    "PreToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'HOOK=\"$(git rev-parse --show-toplevel 2>/dev/null)/.agents/hooks/septum-pre-write.sh\"; if [ -f \"$HOOK\" ]; then exec \"$HOOK\"; else exit 0; fi'",
+            "timeout": 10,
+          },
+        ],
+      },
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'HOOK=\"$(git rev-parse --show-toplevel 2>/dev/null)/.agents/hooks/septum-post-write.sh\"; if [ -f \"$HOOK\" ]; then exec \"$HOOK\"; else exit 0; fi'",
+            "timeout": 15,
+          },
+        ],
+      },
+    ],
+  },
+};
+
+export const SEPTUM_PRE_WRITE_SCRIPT = `#!/usr/bin/env sh
+# Septum 3-Gate Boundary Guard Pre-Write Hook
+# Intercepts write_to_file and replace_file_content before disk mutation
+
+ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+if [ ! -f "$ROOT_DIR/.septum/septum.db" ]; then
+  exit 0
+fi
+
+# Delegate directly to Septum's active 3-gate hook engine
+if command -v bun >/dev/null 2>&1 && [ -f "$ROOT_DIR/bin/septum.ts" ]; then
+  exec bun run "$ROOT_DIR/bin/septum.ts" hook pre-write
+elif command -v septum >/dev/null 2>&1; then
+  exec septum hook pre-write
+elif [ -f "$ROOT_DIR/node_modules/.bin/septum" ]; then
+  exec "$ROOT_DIR/node_modules/.bin/septum" hook pre-write
+elif command -v bunx >/dev/null 2>&1; then
+  exec bunx septum hook pre-write
+fi
+
+exit 0
+`;
+
+export const SEPTUM_POST_WRITE_SCRIPT = `#!/usr/bin/env sh
+# Septum Automated Incremental Post-Write Hook
+# Syncs modified AST into SQLite SSOT after file mutations
+
+ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+if [ ! -f "$ROOT_DIR/.septum/septum.db" ]; then
+  exit 0
+fi
+
+# Trigger background incremental sync
+if command -v bun >/dev/null 2>&1 && [ -f "$ROOT_DIR/bin/septum.ts" ]; then
+  bun run "$ROOT_DIR/bin/septum.ts" sync --json >/dev/null 2>&1 &
+elif command -v septum >/dev/null 2>&1; then
+  septum sync --json >/dev/null 2>&1 &
+elif [ -f "$ROOT_DIR/node_modules/.bin/septum" ]; then
+  "$ROOT_DIR/node_modules/.bin/septum" sync --json >/dev/null 2>&1 &
+elif command -v bunx >/dev/null 2>&1; then
+  bunx septum sync --json >/dev/null 2>&1 &
+fi
+
+exit 0
+`;
+

package/src/cli/templates/rules.ts

@@ -1,38 +1,38 @@
-export const SEPTUM_RULES_TEMPLATE = `# Septum Bounded-Context & Anti-Poisoning Partition Rules
-
-> **Prinsip Utama:** Proyek ini menggunakan **Septum** untuk menegakkan batasan arsitektur (bounded-context) secara deterministik. Setiap AI Coding Agent wajib mematuhi aturan batas domain dan touchpoint berikut.
-
----
-
-## 1. Single Source of Truth (SSOT) via Septum MCP
-
-Sebelum menulis atau mengedit file backend/domain:
-1. **Dilarang Menebak Kontrak Domain:**
-   Gunakan tool MCP \`septum_get_domain_catalog(domain: "...")\` untuk memeriksa file, arketipe, dan signature publik yang sah di dalam domain tersebut.
-2. **Kunci Scope pada Fitur Aktif:**
-   Jika sedang mengerjakan fitur spesifik yang terdaftar di katalog Septum, panggil \`septum_get_feature_context(feature: "...")\`.
-   * **Wajib patuhi \`allowed_touchpoints\`:** Jangan menyentuh atau memodifikasi file di luar daftar yang diizinkan untuk fitur tersebut.
-   * **Wajib gunakan ulang \`reuse_symbols\`:** Jangan membuat fungsi atau helper duplikat jika simbol tersebut sudah terdaftar di \`reuse_symbols\`.
-
----
-
-## 2. Pre-Flight Boundary Check Sebelum Menulis Kode
-
-Sebelum mengeksekusi penulisan file (\`write_to_file\` atau \`replace_file_content\`):
-1. Panggil tool MCP:
-   \`\`\`json
-   septum_check_boundary({
-     "file_path": "path/ke/file.ts",
-     "proposed_imports": ["target_import_statement"],
-     "feature_key": "nama_fitur_opsional"
-   })
-   \`\`\`
-2. **Rejection Handling:** Jika Septum mengembalikan status \`rejected\` (\`forbidden_dependency\`, \`disallowed_dependency\`, atau \`touchpoint_violation\`), **BATALKAN** rencana penulisan tersebut dan cari rute arsitektur yang sah (misal melalui Interface/Shared-Kernel yang diizinkan).
-
----
-
-## 3. Anti Local Scope Myopia
-
-* Dilarang menghapus fungsi publik atau mengubah signature class hanya karena fungsi tersebut tidak terlihat dipanggil di file lokal yang sedang diedit.
-* Pastikan seluruh dependensi inbound/outbound mematuhi batasan domain yang terdaftar di database Septum (\`.septum/septum.db\`).
-`;
+export const SEPTUM_RULES_TEMPLATE = `# Septum Bounded-Context & Anti-Poisoning Partition Rules
+
+> **Prinsip Utama:** Proyek ini menggunakan **Septum** untuk menegakkan batasan arsitektur (bounded-context) secara deterministik. Setiap AI Coding Agent wajib mematuhi aturan batas domain dan touchpoint berikut.
+
+---
+
+## 1. Single Source of Truth (SSOT) via Septum MCP
+
+Sebelum menulis atau mengedit file backend/domain:
+1. **Dilarang Menebak Kontrak Domain:**
+   Gunakan tool MCP \`septum_get_domain_catalog(domain: "...")\` untuk memeriksa file, arketipe, dan signature publik yang sah di dalam domain tersebut.
+2. **Kunci Scope pada Fitur Aktif:**
+   Jika sedang mengerjakan fitur spesifik yang terdaftar di katalog Septum, panggil \`septum_get_feature_context(feature: "...")\`.
+   * **Wajib patuhi \`allowed_touchpoints\`:** Jangan menyentuh atau memodifikasi file di luar daftar yang diizinkan untuk fitur tersebut.
+   * **Wajib gunakan ulang \`reuse_symbols\`:** Jangan membuat fungsi atau helper duplikat jika simbol tersebut sudah terdaftar di \`reuse_symbols\`.
+
+---
+
+## 2. Pre-Flight Boundary Check Sebelum Menulis Kode
+
+Sebelum mengeksekusi penulisan file (\`write_to_file\` atau \`replace_file_content\`):
+1. Panggil tool MCP:
+   \`\`\`json
+   septum_check_boundary({
+     "file_path": "path/ke/file.ts",
+     "proposed_imports": ["target_import_statement"],
+     "feature_key": "nama_fitur_opsional"
+   })
+   \`\`\`
+2. **Rejection Handling:** Jika Septum mengembalikan status \`rejected\` (\`forbidden_dependency\`, \`disallowed_dependency\`, atau \`touchpoint_violation\`), **BATALKAN** rencana penulisan tersebut dan cari rute arsitektur yang sah (misal melalui Interface/Shared-Kernel yang diizinkan).
+
+---
+
+## 3. Anti Local Scope Myopia
+
+* Dilarang menghapus fungsi publik atau mengubah signature class hanya karena fungsi tersebut tidak terlihat dipanggil di file lokal yang sedang diedit.
+* Pastikan seluruh dependensi inbound/outbound mematuhi batasan domain yang terdaftar di database Septum (\`.septum/septum.db\`).
+`;