@moreih29/nexus-core 0.12.0 → 0.13.0

package/assets/hooks/prompt-router/handler.ts

@@ -0,0 +1,261 @@
+import type { HookHandler, NexusHookOutput } from "../../../src/hooks/types.js";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import {
+  expandInvocations,
+  type InvocationsMap,
+  type Harness,
+} from "../../../src/shared/invocations.js";
+
+// Tag priority: specific variants first (m:gc > m, rule:name > rule, plan:auto > plan, init:reset > init)
+const TAG_PATTERNS: Array<{ name: string; regex: RegExp }> = [
+  { name: "plan:auto", regex: /\[plan:auto\]/ },
+  { name: "plan", regex: /\[plan\](?!\w)/ },
+  { name: "run", regex: /\[run\](?!\w)/ },
+  { name: "d", regex: /\[d\](?!\w)/ },
+  { name: "m:gc", regex: /\[m:gc\]/ },
+  { name: "m", regex: /\[m\](?!\w)/ },
+  { name: "rule:name", regex: /\[rule:([a-zA-Z0-9_-]+)\]/ },
+  { name: "rule", regex: /\[rule\](?!\w)/ },
+  { name: "sync", regex: /\[sync\](?!\w)/ },
+  { name: "init:reset", regex: /\[init:reset\]/ },
+  { name: "init", regex: /\[init\](?!\w)/ },
+];
+
+// ---------------------------------------------------------------------------
+// Invocations loader — cached per process
+// ---------------------------------------------------------------------------
+
+let _invocationsCache: InvocationsMap | null = null;
+
+function loadInvocations(): InvocationsMap {
+  if (_invocationsCache) return _invocationsCache;
+
+  const selfDir = new URL(".", import.meta.url).pathname;
+  // Walk up from handler directory to find assets/tools/tool-name-map.yml
+  let dir = selfDir;
+  while (dir !== "/") {
+    const candidate = resolve(dir, "assets/tools/tool-name-map.yml");
+    if (existsSync(candidate)) {
+      const raw = readFileSync(candidate, "utf-8");
+      const parsed = parseYaml(raw) as { invocations?: InvocationsMap };
+      if (!parsed.invocations) {
+        throw new Error("[prompt-router] tool-name-map.yml missing 'invocations' section");
+      }
+      _invocationsCache = parsed.invocations;
+      return _invocationsCache;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(`[prompt-router] Cannot locate assets/tools/tool-name-map.yml from ${selfDir}`);
+}
+
+// ---------------------------------------------------------------------------
+// Harness resolution
+// ---------------------------------------------------------------------------
+
+function resolveHarness(): Harness {
+  const h = process.env["NEXUS_HARNESS"];
+  if (h === "claude" || h === "opencode" || h === "codex") return h;
+  if (h) {
+    process.stderr.write(
+      `[prompt-router] Unknown NEXUS_HARNESS="${h}", falling back to "claude"\n`
+    );
+  }
+  return "claude";
+}
+
+// ---------------------------------------------------------------------------
+// Invocation expansion helper
+// ---------------------------------------------------------------------------
+
+function expand(template: string, harness: Harness): string {
+  return expandInvocations(template, harness, loadInvocations());
+}
+
+// ---------------------------------------------------------------------------
+// Rule target loader
+// ---------------------------------------------------------------------------
+
+function loadValidRuleTargets(cwd: string): string[] {
+  const targets: string[] = [];
+  for (const dir of ["assets/agents", "assets/skills"]) {
+    const absDir = join(cwd, dir);
+    if (!existsSync(absDir)) continue;
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) targets.push(entry.name);
+    }
+  }
+  return targets;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+const handler: HookHandler = async (input): Promise<NexusHookOutput | void> => {
+  if (input.hook_event_name !== "UserPromptSubmit") return;
+
+  const prompt = input.prompt;
+  const detected: Array<{ name: string; arg?: string }> = [];
+
+  // Detect all tags — use seen Set keyed on base tag name to prevent duplicates
+  // (e.g. plan:auto and plan share base "plan"; whichever appears first wins)
+  const seen = new Set<string>();
+  for (const { name, regex } of TAG_PATTERNS) {
+    const m = regex.exec(prompt);
+    if (!m) continue;
+    const base = name.split(":")[0];
+    if (seen.has(base)) continue;
+    seen.add(base);
+    detected.push({ name, arg: m[1] });
+  }
+
+  const sessionDir = join(input.cwd, ".nexus/state", input.session_id);
+  const planPath = join(sessionDir, "plan.json");
+  const tasksPath = join(sessionDir, "tasks.json");
+  const hasPlan = existsSync(planPath);
+  const hasTasks = existsSync(tasksPath);
+
+  const harness = resolveHarness();
+
+  const notices: string[] = [];
+  let decision: "block" | undefined;
+  let block_reason: string | undefined;
+
+  for (const tag of detected) {
+    switch (tag.name) {
+      case "plan":
+        notices.push(
+          `<system-notice>[plan] tag detected. ${expand('{{skill_activation skill="nx-plan"}}', harness)} for structured planning.</system-notice>`
+        );
+        break;
+
+      case "plan:auto":
+        notices.push(
+          `<system-notice>[plan:auto] tag detected. ${expand('{{skill_activation skill="nx-plan" mode="auto"}}', harness)} for structured planning.</system-notice>`
+        );
+        break;
+
+      case "run":
+        if (!hasTasks) {
+          notices.push(
+            `<system-notice>[run] tag detected but no tasks.json. ${expand('{{skill_activation skill="nx-plan"}}', harness)} with args "auto" first to generate tasks, then run.</system-notice>`
+          );
+        } else {
+          notices.push(
+            `<system-notice>[run] tag detected. ${expand('{{skill_activation skill="nx-run"}}', harness)} to execute tasks.</system-notice>`
+          );
+        }
+        break;
+
+      case "d":
+        if (!hasPlan) {
+          decision = "block";
+          block_reason =
+            `[d] tag requires an active plan session. ${expand('{{skill_activation skill="nx-plan"}}', harness)} first.`;
+        } else {
+          notices.push(
+            `<system-notice>[d] tag detected. Record decision via \`nx_plan_decide(issue_id, summary)\` MCP tool.</system-notice>`
+          );
+        }
+        break;
+
+      case "m":
+        notices.push(
+          `<system-notice>[m] tag detected. Save a memory note to \`.nexus/memory/<prefix>-<name>.md\`. Prefix: empirical-, external-, or pattern- (see architecture.md §2-1).</system-notice>`
+        );
+        break;
+
+      case "m:gc":
+        notices.push(
+          `<system-notice>[m:gc] tag detected. Review \`.nexus/memory/\` for stale or duplicate entries and consolidate.</system-notice>`
+        );
+        break;
+
+      case "rule": {
+        const valid = loadValidRuleTargets(input.cwd);
+        notices.push(
+          `<system-notice>[rule] tag detected. Determine target from intent. Valid targets: ${valid.join(", ")}. Update \`.nexus/rules/<target>.md\`.</system-notice>`
+        );
+        break;
+      }
+
+      case "rule:name": {
+        const valid = loadValidRuleTargets(input.cwd);
+        const name = tag.arg ?? "";
+        if (!valid.includes(name)) {
+          decision = "block";
+          block_reason = `[rule:${name}] invalid — must be one of: ${valid.join(", ")}`;
+        } else {
+          notices.push(
+            `<system-notice>[rule:${name}] tag detected. Update \`.nexus/rules/${name}.md\` with user's directive.</system-notice>`
+          );
+        }
+        break;
+      }
+
+      case "sync":
+        notices.push(
+          `<system-notice>[sync] tag detected. ${expand('{{skill_activation skill="nx-sync"}}', harness)} to synchronize \`.nexus/context/\`.</system-notice>`
+        );
+        break;
+
+      case "init":
+        notices.push(
+          `<system-notice>[init] tag detected. ${expand('{{skill_activation skill="nx-init"}}', harness)} for project onboarding.</system-notice>`
+        );
+        break;
+
+      case "init:reset":
+        notices.push(
+          `<system-notice>[init:reset] tag detected. ${expand('{{skill_activation skill="nx-init" mode="reset"}}', harness)} for full re-initialization.</system-notice>`
+        );
+        break;
+    }
+  }
+
+  // No tags detected + active state → emit state notice
+  if (detected.length === 0) {
+    if (hasPlan) {
+      try {
+        const plan = JSON.parse(readFileSync(planPath, "utf-8")) as {
+          topic?: string;
+          issues?: Array<{ status: string }>;
+        };
+        const pending = plan.issues?.filter((i) => i.status === "pending").length ?? 0;
+        notices.push(
+          `<system-notice>Active plan session: "${plan.topic ?? "(unknown)"}", ${pending} issues pending.</system-notice>`
+        );
+      } catch {
+        // Malformed plan.json — skip notice
+      }
+    } else if (hasTasks) {
+      try {
+        const tasks = JSON.parse(readFileSync(tasksPath, "utf-8")) as {
+          tasks?: Array<{ status: string }>;
+        };
+        const pending = tasks.tasks?.filter((t) => t.status !== "completed").length ?? 0;
+        if (pending > 0) {
+          notices.push(
+            `<system-notice>Active run session: ${pending} tasks remaining in tasks.json.</system-notice>`
+          );
+        }
+      } catch {
+        // Malformed tasks.json — skip notice
+      }
+    }
+  }
+
+  if (decision === "block") {
+    return { decision, block_reason };
+  }
+  if (notices.length === 0) return;
+  return { additional_context: notices.join("\n\n") };
+};
+
+export default handler;

package/assets/hooks/prompt-router/meta.yml

@@ -0,0 +1,11 @@
+name: prompt-router
+description: Detect nexus tags, inject state notices and skill invocation guidance
+events: [UserPromptSubmit]
+matcher: "*"
+timeout: 10
+fallback: warn
+priority: 0
+requires_capabilities:
+  - event.user_prompt_submit
+  - output.additional_context.user_prompt
+  - output.decision_block

package/assets/hooks/session-init/handler.test.ts

@@ -0,0 +1,274 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import handler from "./handler.ts";
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(
+    path.join(os.tmpdir(), `nexus-session-init-${crypto.randomUUID()}-`)
+  );
+}
+
+function sessionDir(cwd: string, sid: string): string {
+  return path.join(cwd, ".nexus/state", sid);
+}
+
+// ---------------------------------------------------------------------------
+// Scenario 1: New session_id (valid) → directory + files created
+// ---------------------------------------------------------------------------
+
+describe("scenario 1 — new session_id creates state files", () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = makeTmpDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("creates .nexus/state/sessions/<sid>/ directory", async () => {
+    const sid = crypto.randomUUID();
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.existsSync(sessionDir(cwd, sid))).toBe(true);
+    expect(fs.statSync(sessionDir(cwd, sid)).isDirectory()).toBe(true);
+  });
+
+  test("creates agent-tracker.json with content '[]'", async () => {
+    const sid = crypto.randomUUID();
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    const filePath = path.join(sessionDir(cwd, sid), "agent-tracker.json");
+    expect(fs.existsSync(filePath)).toBe(true);
+    expect(fs.readFileSync(filePath, "utf8")).toBe("[]");
+  });
+
+  test("creates tool-log.jsonl as empty file", async () => {
+    const sid = crypto.randomUUID();
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    const filePath = path.join(sessionDir(cwd, sid), "tool-log.jsonl");
+    expect(fs.existsSync(filePath)).toBe(true);
+    expect(fs.readFileSync(filePath, "utf8")).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario 2: Existing session_id re-invoked → files overwritten (reset policy)
+// ---------------------------------------------------------------------------
+
+describe("scenario 2 — existing session_id re-initialises (overwrite)", () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = makeTmpDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("overwrites agent-tracker.json even when it had prior content", async () => {
+    const sid = crypto.randomUUID();
+    // First call
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    // Simulate prior state
+    const trackerPath = path.join(sessionDir(cwd, sid), "agent-tracker.json");
+    fs.writeFileSync(trackerPath, '[{"id":"agent-1"}]');
+    // Second call — must reset
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.readFileSync(trackerPath, "utf8")).toBe("[]");
+  });
+
+  test("overwrites tool-log.jsonl even when it had prior content", async () => {
+    const sid = crypto.randomUUID();
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    const logPath = path.join(sessionDir(cwd, sid), "tool-log.jsonl");
+    fs.writeFileSync(logPath, '{"tool":"Bash","ts":"2026-01-01T00:00:00Z"}\n');
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.readFileSync(logPath, "utf8")).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario 3: Path traversal — session_id="../etc/passwd"
+// ---------------------------------------------------------------------------
+
+describe("scenario 3 — path traversal is prevented", () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = makeTmpDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("does not write to the real /etc/passwd (mtime unchanged)", async () => {
+    // Guard: confirm /etc/passwd exists so the test is meaningful
+    expect(fs.existsSync("/etc/passwd")).toBe(true);
+    const before = fs.statSync("/etc/passwd").mtimeMs;
+    await handler({
+      hook_event_name: "SessionStart",
+      session_id: "../etc/passwd",
+      cwd,
+    });
+    const after = fs.statSync("/etc/passwd").mtimeMs;
+    expect(after).toBe(before);
+  });
+
+  test("any created path is contained within cwd", async () => {
+    await handler({
+      hook_event_name: "SessionStart",
+      session_id: "../etc/passwd",
+      cwd,
+    });
+    // Walk everything created and assert it all lives inside cwd
+    const sessionsRoot = path.join(cwd, ".nexus/state");
+    if (fs.existsSync(sessionsRoot)) {
+      const entries = fs.readdirSync(sessionsRoot, { recursive: true, encoding: "utf8" }) as string[];
+      for (const entry of entries) {
+        const abs = path.resolve(sessionsRoot, entry);
+        expect(abs.startsWith(cwd)).toBe(true);
+      }
+    }
+  });
+
+  test("basename extraction: if something is created it is named 'passwd' inside sessions", async () => {
+    await handler({
+      hook_event_name: "SessionStart",
+      session_id: "../etc/passwd",
+      cwd,
+    });
+    // basename('../etc/passwd') === 'passwd'
+    // Handler must either create state/passwd (safe) or nothing.
+    // It must NOT create state/../etc/passwd (which resolves to .nexus/etc/passwd — still inside cwd but wrong semantic).
+    // The only acceptable directory name is 'passwd' directly under state.
+    const sessionsRoot = path.join(cwd, ".nexus/state");
+    if (fs.existsSync(sessionsRoot)) {
+      const children = fs.readdirSync(sessionsRoot);
+      // Each direct child must be a non-traversal name
+      for (const child of children) {
+        expect(child).not.toContain("..");
+        expect(child).not.toContain("/");
+      }
+    }
+  });
+
+  test("session_id with embedded slash is rejected or sanitised — no nested subdirs under sessions", async () => {
+    const sid = "foo/bar";
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    // If handler created something it must not be a nested foo/bar under state.
+    // Acceptable: nothing, or state/bar (basename). Not acceptable: state/foo/bar.
+    const fooInsideSessions = path.join(cwd, ".nexus/state/foo");
+    if (fs.existsSync(fooInsideSessions)) {
+      // foo exists — bar must NOT be a subdirectory of it (that would be nested traversal)
+      expect(fs.existsSync(path.join(fooInsideSessions, "bar"))).toBe(false);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario 4: plan.json, tasks.json, memory-access.jsonl are not touched
+// ---------------------------------------------------------------------------
+
+describe("scenario 4 — project-level state files are not modified", () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = makeTmpDir();
+    // Seed pre-existing project-level state files
+    const stateDir = path.join(cwd, ".nexus/state");
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, "plan.json"), '{"version":1}');
+    fs.writeFileSync(path.join(stateDir, "tasks.json"), '{"tasks":[]}');
+    fs.writeFileSync(path.join(stateDir, "memory-access.jsonl"), "entry1\n");
+  });
+
+  afterEach(() => {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("plan.json content is unchanged after handler runs", async () => {
+    const sid = crypto.randomUUID();
+    const planPath = path.join(cwd, ".nexus/state/plan.json");
+    const before = fs.readFileSync(planPath, "utf8");
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.readFileSync(planPath, "utf8")).toBe(before);
+  });
+
+  test("tasks.json content is unchanged after handler runs", async () => {
+    const sid = crypto.randomUUID();
+    const tasksPath = path.join(cwd, ".nexus/state/tasks.json");
+    const before = fs.readFileSync(tasksPath, "utf8");
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.readFileSync(tasksPath, "utf8")).toBe(before);
+  });
+
+  test("memory-access.jsonl content is unchanged after handler runs", async () => {
+    const sid = crypto.randomUUID();
+    const memPath = path.join(cwd, ".nexus/state/memory-access.jsonl");
+    const before = fs.readFileSync(memPath, "utf8");
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.readFileSync(memPath, "utf8")).toBe(before);
+  });
+
+  test("plan.json mtime is unchanged after handler runs", async () => {
+    const sid = crypto.randomUUID();
+    const planPath = path.join(cwd, ".nexus/state/plan.json");
+    const before = fs.statSync(planPath).mtimeMs;
+    await handler({ hook_event_name: "SessionStart", session_id: sid, cwd });
+    expect(fs.statSync(planPath).mtimeMs).toBe(before);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario 5: Return value is undefined / void
+// ---------------------------------------------------------------------------
+
+describe("scenario 5 — return value is undefined (void)", () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = makeTmpDir();
+  });
+
+  afterEach(() => {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("returns undefined for a valid SessionStart event", async () => {
+    const sid = crypto.randomUUID();
+    const result = await handler({
+      hook_event_name: "SessionStart",
+      session_id: sid,
+      cwd,
+    });
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined when hook_event_name is not SessionStart", async () => {
+    const result = await handler({
+      hook_event_name: "UserPromptSubmit",
+      session_id: crypto.randomUUID(),
+      cwd,
+      prompt: "hello",
+    });
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined for path traversal input (rejected)", async () => {
+    const result = await handler({
+      hook_event_name: "SessionStart",
+      session_id: "../etc/passwd",
+      cwd,
+    });
+    expect(result).toBeUndefined();
+  });
+});

package/assets/hooks/session-init/handler.ts

@@ -0,0 +1,30 @@
+import type { HookHandler } from "../../../src/hooks/types.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+const handler: HookHandler = async (input) => {
+  if (input.hook_event_name !== "SessionStart") return;
+
+  // Sanitize session_id to prevent path traversal
+  const safeSid = basename(input.session_id);
+  if (!safeSid || safeSid.startsWith(".") || safeSid.includes("/")) {
+    process.stderr.write(`[session-init] invalid session_id: ${input.session_id}\n`);
+    return;
+  }
+
+  const sessionDir = join(input.cwd, ".nexus/state", safeSid);
+
+  // Ensure directory exists (idempotent)
+  mkdirSync(sessionDir, { recursive: true });
+
+  // Initialize per-session state files — overwrite unconditionally (resume is intentional)
+  writeFileSync(join(sessionDir, "agent-tracker.json"), "[]");
+  writeFileSync(join(sessionDir, "tool-log.jsonl"), "");
+
+  // plan.json and tasks.json are MCP responsibility — not touched here
+  // memory-access.jsonl is project-level — not touched here
+
+  // No additional_context returned (decided: no context injection at session start)
+};
+
+export default handler;

package/assets/hooks/session-init/meta.yml

@@ -0,0 +1,9 @@
+name: session-init
+description: Initialize per-session state files at session start
+events: [SessionStart]
+matcher: "*"
+timeout: 10
+fallback: warn
+priority: 0
+requires_capabilities:
+  - event.session_start

package/assets/lsp-servers.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "./schema/lsp-servers.schema.json",
+  "languages": {
+    "typescript": {
+      "extensions": {
+        "ts": "typescript",
+        "tsx": "typescriptreact",
+        "js": "javascript",
+        "jsx": "javascriptreact",
+        "mjs": "javascript",
+        "cjs": "javascript",
+        "mts": "typescript",
+        "cts": "typescript"
+      },
+      "server": {
+        "command_chain": ["bunx", "npx"],
+        "args": ["typescript-language-server", "--stdio"]
+      },
+      "install_hint": "npm i -g typescript-language-server"
+    },
+    "python": {
+      "extensions": {
+        "py": "python",
+        "pyi": "python"
+      },
+      "server": {
+        "command_chain": ["bunx", "npx"],
+        "args": ["pyright-langserver", "--stdio"]
+      },
+      "install_hint": "npm i -g pyright"
+    },
+    "rust": {
+      "extensions": {
+        "rs": "rust"
+      },
+      "server": {
+        "command_chain": ["rust-analyzer"],
+        "search_paths": ["~/.cargo/bin/rust-analyzer"],
+        "args": []
+      },
+      "install_hint": "rustup component add rust-analyzer"
+    },
+    "go": {
+      "extensions": {
+        "go": "go"
+      },
+      "server": {
+        "command_chain": ["gopls"],
+        "search_paths": ["~/go/bin/gopls", "/usr/local/go/bin/gopls"],
+        "args": ["serve"]
+      },
+      "install_hint": "go install golang.org/x/tools/gopls@latest"
+    }
+  }
+}