plugnz 0.0.22 → 0.0.24

package/dist/hook-runtime.mjs

@@ -1,12 +1,22 @@
 // src/hooks.ts
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 var HOOK_EVENTS = ["session.start", "turn.stop", "tool.before", "tool.after"];
 var HOOK_CONFIG_FILE = "plugnz.hooks.json";
 var DEFAULT_HOOK_TIMEOUT_MS = 1e4;
 var MAX_HOOK_TIMEOUT_MS = 60000;
 var MAX_HOOK_OUTPUT_BYTES = 1048576;
+var HOOK_EFFECTS = ["context", "continue"];
+function hookEffectGap(required, supported) {
+  for (const effect of HOOK_EFFECTS) {
+    if (required?.[effect] !== true)
+      continue;
+    if (supported?.[effect] !== true)
+      return { effect, status: supported?.[effect] === false ? "unsupported" : "unverified" };
+  }
+  return null;
+}
 function record(value, label) {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     throw new Error(label + " must be an object");
@@ -31,8 +41,9 @@ function isHookEvent(value) {
 function validateHookConfig(value) {
   const root = record(value, "Hook configuration");
   keys(root, ["version", "hooks"], "Hook configuration");
-  if (root["version"] !== 1)
-    throw new Error("Hook configuration version must be 1");
+  const version = root["version"];
+  if (version !== 1 && version !== 2)
+    throw new Error("Hook configuration version must be 1 or 2");
   const sourceHooks = record(root["hooks"], "hooks");
   keys(sourceHooks, HOOK_EVENTS, "hooks");
   const hooks = {};
@@ -45,7 +56,22 @@ function validateHookConfig(value) {
     hooks[event] = handlers.map((value, index) => {
       const label = event + "[" + index + "]";
       const handler = record(value, label);
-      keys(handler, ["command", "tools", "timeoutMs"], label);
+      keys(handler, version === 1 ? ["command", "tools", "timeoutMs"] : ["command", "tools", "timeoutMs", "requires"], label);
+      let requires;
+      if (version === 2) {
+        const effects = handler["requires"] === undefined ? {} : record(handler["requires"], label + ".requires");
+        keys(effects, HOOK_EFFECTS, label + ".requires");
+        for (const effect of HOOK_EFFECTS) {
+          if (effects[effect] !== undefined && typeof effects[effect] !== "boolean")
+            throw new Error(label + ".requires." + effect + " must be boolean");
+        }
+        requires = { ...effects };
+        if (requires.continue === true && event !== "turn.stop")
+          throw new Error(label + ": continue is only available at turn.stop");
+        if (event === "turn.stop" && requires.context === true !== (requires.continue === true)) {
+          throw new Error(label + ": turn.stop requires context:true and continue:true together");
+        }
+      }
       const command = handler["command"];
       if (!Array.isArray(command) || command.length === 0)
         throw new Error(label + ".command must be a nonempty argv array");
@@ -63,15 +89,25 @@ function validateHookConfig(value) {
       if (timeout !== undefined && (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout < 1 || timeout > MAX_HOOK_TIMEOUT_MS)) {
         throw new Error(label + ".timeoutMs must be an integer from 1 to " + MAX_HOOK_TIMEOUT_MS);
       }
-      return { command: argv, ...tools === undefined ? {} : { tools }, ...timeout === undefined ? {} : { timeoutMs: timeout } };
+      return { command: argv, ...tools === undefined ? {} : { tools }, ...timeout === undefined ? {} : { timeoutMs: timeout }, ...requires === undefined ? {} : { requires } };
     });
   }
-  return { version: 1, hooks };
+  return { version, hooks };
 }
 function readHookConfig(pluginRoot) {
   const path = join(pluginRoot, HOOK_CONFIG_FILE);
-  if (!existsSync(path))
-    return;
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+  if (stat.isSymbolicLink())
+    throw new Error("Hook source symlinks are unsupported: " + path);
+  if (!stat.isFile())
+    throw new Error("Hook manifest must be a regular file: " + path);
   let value;
   try {
     value = JSON.parse(readFileSync(path, "utf8"));
@@ -179,6 +215,12 @@ async function runHooks(configValue, inputValue, pluginRoot) {
         }
       }
       const result = validateHookResult(raw, input);
+      if (config.version === 2) {
+        if (result.context !== undefined && handler.requires?.context !== true)
+          throw new Error("undeclared context effect; declare requires.context:true");
+        if (result.continue === true && handler.requires?.continue !== true)
+          throw new Error("undeclared continuation effect; declare requires.continue:true");
+      }
       if (result.context !== undefined)
         contexts.push(result.context);
       if (result.continue !== undefined)
@@ -277,9 +319,11 @@ function executeHandler(handler, input, pluginRoot) {
 export {
   DEFAULT_HOOK_TIMEOUT_MS,
   HOOK_CONFIG_FILE,
+  HOOK_EFFECTS,
   HOOK_EVENTS,
   MAX_HOOK_OUTPUT_BYTES,
   MAX_HOOK_TIMEOUT_MS,
+  hookEffectGap,
   readHookConfig,
   runHooks,
   validateHookConfig,