@orchestrator-claude/definitions 3.32.1 → 3.33.0

package/hooks/gate-guardian.mjs

@@ -0,0 +1,463 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../project-root-resolver/dist/index.js
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  let currentDir = cwd;
+  for (; ; ) {
+    if (existsSync(join(currentDir, sentinel))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+// hooks/lib/api-client.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
+var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+var JWT_CACHE = join2(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
+var projectIdResolutionAttempted = false;
+async function ensureProjectIdResolved(token) {
+  if (PROJECT_ID || projectIdResolutionAttempted) return;
+  projectIdResolutionAttempted = true;
+  try {
+    const rootPath = resolveHookProjectRoot(process.cwd());
+    if (rootPath === null) {
+      log(
+        "API-CLIENT",
+        "ensureProjectIdResolved: cwd not registered (.orchestrator sentinel not found) \u2014 skipping"
+      );
+      return;
+    }
+    const resolved = await resolveProjectIdByPath(rootPath, token);
+    if (resolved) {
+      PROJECT_ID = resolved;
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: resolved projectId=${resolved} rootPath=${rootPath}`
+      );
+    } else {
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: rootPath=${rootPath} not registered to any project \u2014 skipping`
+      );
+    }
+  } catch (err) {
+    log(
+      "API-CLIENT",
+      `ensureProjectIdResolved: unexpected failure \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+function getCachedToken() {
+  try {
+    const stat = statSync(JWT_CACHE);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < 35e5) {
+      return readFileSync(JWT_CACHE, "utf-8").trim();
+    }
+  } catch {
+  }
+  return null;
+}
+async function login() {
+  try {
+    const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-ID": PROJECT_ID
+      },
+      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    const token = data.accessToken || data.data?.accessToken || "";
+    if (token) {
+      writeFileSync(JWT_CACHE, token);
+    }
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+async function getToken() {
+  const token = getCachedToken() || await login();
+  if (token) {
+    await ensureProjectIdResolved(token);
+  }
+  return token;
+}
+async function apiGet(path, token, timeoutMs = 5e3) {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID
+      },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+async function resolveProjectIdByPath(rootPath, token) {
+  const resp = await apiGet(
+    `/api/v1/projects/resolve?rootPath=${encodeURIComponent(rootPath)}`,
+    token
+  );
+  return resp?.projectId ?? null;
+}
+async function getWorkflowStatus(workflowId) {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/status`, token);
+}
+async function getWorkflowMode(workflowId) {
+  const status = await getWorkflowStatus(workflowId);
+  if (!status) return null;
+  return status.executionMode ?? status.mode ?? null;
+}
+async function getNextAction(workflowId) {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/pending-action`, token);
+}
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
+async function getWorkflowTypeAndVariant(workflowId, token) {
+  try {
+    const resp = await apiGet(`/api/v1/workflows/${workflowId}/status`, token);
+    if (!resp) return null;
+    const { type, variant } = resp;
+    if (!type || !variant) return null;
+    return { type, variant };
+  } catch {
+    return null;
+  }
+}
+async function getGateCellMode(typeId, variant, gateKey, token) {
+  try {
+    const resp = await apiGet(`/api/v1/workflow-definitions/${typeId}`, token);
+    if (!resp) return null;
+    const cell = resp.modes?.[variant]?.gates?.[gateKey];
+    if (cell === "REQ" || cell === "OPT" || cell === "SKIP") return cell;
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function getAdversarialVerdict(workflowId, token) {
+  try {
+    const resp = await apiGet(`/api/v1/artifact-content/${workflowId}/adversarial_review`, token);
+    if (!resp) return null;
+    const { verdict, iteration } = resp.metadata ?? {};
+    if (typeof verdict !== "string" || typeof iteration !== "number") return null;
+    return { verdict, iteration };
+  } catch {
+    return null;
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+function outputPreToolUse(opts) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: opts.decision,
+      ...opts.reason && { permissionDecisionReason: opts.reason },
+      ...opts.context && { additionalContext: opts.context }
+    }
+  };
+  console.log(JSON.stringify(output));
+}
+
+// hooks/lib/gate-logic.ts
+function classifyRisk(targetPhase) {
+  if (/implement|deploy|migrate|delete/i.test(targetPhase)) {
+    return "HIGH";
+  }
+  return "LOW";
+}
+function deriveGateStrategy(ctx) {
+  if (ctx.riskLevel === "HIGH") {
+    return {
+      strategy: "ASK_HUMAN",
+      reason: `Phase '${ctx.targetPhase}' is high-risk and requires human approval before proceeding.`
+    };
+  }
+  return {
+    strategy: "AUTO_APPROVE",
+    reason: `Phase '${ctx.targetPhase}' is low-risk \u2014 auto-approved.`
+  };
+}
+
+// hooks/gate-guardian.ts
+var HOOK = "GATE-GUARDIAN";
+var PME_HARD_CAP = 3;
+var defaultDeps = {
+  readStdin,
+  getWorkflowMode,
+  getToken,
+  getNextAction,
+  getWorkflowTypeAndVariant,
+  getGateCellMode,
+  getAdversarialVerdict,
+  output: outputPreToolUse,
+  log
+};
+async function mainWithDeps(deps) {
+  const {
+    readStdin: readStdin2,
+    getWorkflowMode: getWorkflowMode2,
+    getToken: getToken2,
+    getNextAction: getNextAction2,
+    getWorkflowTypeAndVariant: getWorkflowTypeAndVariant2,
+    getGateCellMode: getGateCellMode2,
+    getAdversarialVerdict: getAdversarialVerdict2,
+    output,
+    log: log2
+  } = deps;
+  const stdin = await readStdin2();
+  log2(HOOK, "PreToolUse advancePhase triggered");
+  const workflowId = getField(stdin, "tool_input.workflowId") || getField(stdin, "workflowId");
+  const targetPhase = getField(stdin, "tool_input.targetPhase") || getField(stdin, "targetPhase");
+  log2(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
+  if (workflowId) {
+    const mode = await getWorkflowMode2(workflowId);
+    log2(HOOK, `workflow=${workflowId} mode=${mode ?? "legacy"}`);
+    if (mode === "quick") {
+      output({
+        decision: "allow",
+        context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`
+      });
+      log2(HOOK, `ALLOW quick mode phase=${targetPhase}`);
+      return;
+    }
+    if (mode === "interactive") {
+      output({
+        decision: "allow",
+        context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`
+      });
+      log2(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
+      return;
+    }
+  }
+  if (!workflowId || !targetPhase) {
+    log2(HOOK, "DENY (could not parse input)");
+    output({
+      decision: "deny",
+      reason: "Gate Guardian: Could not parse workflowId or targetPhase.",
+      context: "Ensure you pass both workflowId and targetPhase to advancePhase."
+    });
+    return;
+  }
+  const token = await getToken2();
+  if (token === null || token === "") {
+    log2(HOOK, "DENY (auth failed)");
+    output({
+      decision: "deny",
+      reason: "Gate Guardian: Authentication failed.",
+      context: "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars."
+    });
+    return;
+  }
+  {
+    const typeVariant = await getWorkflowTypeAndVariant2(workflowId, token);
+    if (typeVariant?.type === "project_management_enterprise") {
+      const gateMode = await getGateCellMode2(
+        typeVariant.type,
+        typeVariant.variant,
+        "adversarial",
+        token
+      );
+      if (gateMode === "REQ") {
+        const verdict = await getAdversarialVerdict2(workflowId, token);
+        if (!verdict) {
+          log2(
+            HOOK,
+            `PME Step 5.5: no adversarial artifact found \u2014 fail-open ALLOW wf=${workflowId}`
+          );
+          output({
+            decision: "allow",
+            context: `[GATE] PME adversarial gate: no artifact found, fail-open ALLOW for '${targetPhase}'.`
+          });
+          return;
+        }
+        if (verdict.iteration >= PME_HARD_CAP) {
+          log2(
+            HOOK,
+            `PME Step 5.5: BLOCKED escalation at hard cap (iteration=${String(verdict.iteration)}) \u2014 ALLOW wf=${workflowId}`
+          );
+          output({
+            decision: "allow",
+            context: `[GATE] PME adversarial gate: hard cap reached (iteration=${String(verdict.iteration)}/${String(PME_HARD_CAP)}), escalating.`
+          });
+          return;
+        }
+        if (verdict.verdict === "PASS") {
+          log2(HOOK, `PME Step 5.5: adversarial verdict=PASS \u2014 ALLOW wf=${workflowId}`);
+          output({
+            decision: "allow",
+            context: `[GATE] PME adversarial gate: verdict=PASS, proceeding to '${targetPhase}'.`
+          });
+          return;
+        }
+        log2(
+          HOOK,
+          `PME Step 5.5: DENY verdict=${verdict.verdict} iteration=${String(verdict.iteration)} wf=${workflowId}`
+        );
+        output({
+          decision: "deny",
+          reason: `Gate Guardian: adversarial_review required \u2014 verdict=${verdict.verdict}, iteration=${String(verdict.iteration)}. Resolve adversarial review before advancing.`
+        });
+        return;
+      }
+      log2(
+        HOOK,
+        `PME Step 5.5: gateMode=${gateMode ?? "null"} \u2014 ALLOW (non-REQ gate) wf=${workflowId}`
+      );
+      output({
+        decision: "allow",
+        context: `[GATE] PME adversarial gate: mode=${gateMode ?? "none"} (non-REQ), proceeding to '${targetPhase}'.`
+      });
+      return;
+    }
+  }
+  if (/implement/i.test(targetPhase)) {
+    log2(HOOK, "Checking approval for IMPLEMENT-type phase");
+    const action = await getNextAction2(workflowId);
+    const status = action?.pendingAction?.status ?? "";
+    if (status === "approved" || status === "awaiting_agent") {
+      output({
+        decision: "allow",
+        context: `[GATE] IMPLEMENT approved (status=${status}): proceeding to phase '${targetPhase}'.`
+      });
+      log2(
+        HOOK,
+        JSON.stringify({
+          hook: "gate-guardian",
+          strategy: "IMPLEMENT_APPROVED",
+          targetPhase,
+          workflowId
+        })
+      );
+      return;
+    }
+    output({
+      decision: "deny",
+      reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status || "not-set"}.`,
+      context: "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction."
+    });
+    log2(
+      HOOK,
+      JSON.stringify({
+        hook: "gate-guardian",
+        strategy: "IMPLEMENT_DENIED",
+        targetPhase,
+        workflowId,
+        reason: "pending-action not approved"
+      })
+    );
+    return;
+  }
+  const riskLevel = classifyRisk(targetPhase);
+  const ctx = {
+    workflowId,
+    targetPhase,
+    // Reserved for Phase 5+6 — will be populated when OLAP integration provides
+    // workflow context. Currently unused by deriveGateStrategy().
+    currentPhase: "",
+    executionMode: null,
+    workflowMode: null,
+    riskLevel
+  };
+  const decision = deriveGateStrategy(ctx);
+  log2(
+    HOOK,
+    JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason })
+  );
+  switch (decision.strategy) {
+    case "AUTO_APPROVE":
+      output({
+        decision: "allow",
+        context: `[GATE] AUTO_APPROVE: ${decision.reason}`
+      });
+      break;
+    case "ASK_HUMAN":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian: ${decision.reason} Ask user for approval.`
+      });
+      break;
+    case "BLOCK_AND_REQUIRE":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian BLOCKED: ${decision.reason}. Required: ${decision.requiredAction ?? "unspecified"}.`
+      });
+      break;
+  }
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch(() => process.exit(0));
+export {
+  mainWithDeps
+};