Merge pull request #106 from JerrettDavis/fix/openclaw-local-install-hook

plugins/openclaw/README.md

@@ -21,23 +21,40 @@ This plugin can auto-start a local `headroom proxy` when needed. OpenClaw treats
 
 ## Local Development Install (Detection-Friendly)
 
-If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths:
+If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths. These linked installs are supported:
 
 ```bash
 cd plugins/openclaw
 npm install
 npm run build
 openclaw plugins install --dangerously-force-unsafe-install --link .
+openclaw plugins install --dangerously-force-unsafe-install --link dist
+```
+
+From the repo root, install the plugin directory explicitly:
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install --link ./plugins/openclaw
+```
+
+Or, from inside `dist/`:
+
+```bash
+cd plugins/openclaw/dist
+openclaw plugins install --dangerously-force-unsafe-install --link .
 ```
 
 Why this matters:
 - The plugin checks launchers in this order: PATH -> local npm bin -> global npm -> python.
-- "local npm bin" means `plugins/openclaw/node_modules/.bin/headroom` relative to the installed plugin root.
-- Using `--link .` from `plugins/openclaw` keeps that local path aligned for detection.
+- "local npm bin" means `plugins/openclaw/node_modules/.bin/headroom` relative to the source checkout.
+- Using `--link dist` (or `--link .` from `dist/`) still keeps runtime code adjacent to the checkout, and launcher detection falls back to PATH/global/python if a local npm bin is not present under the installed root.
+- `plugins/openclaw` also carries a no-op hook shim so OpenClaw's hook-pack fallback treats the path as valid instead of emitting a misleading `package.json missing openclaw.hooks` warning.
 - If you install from a `.tgz`, local npm bin may not exist in the installed extension and detection will fall back to PATH/global/python.
 
 ## Configure
 
+Install automatically selects the `contextEngine` slot for `headroom` on current OpenClaw releases. If you need to switch back manually, set `plugins.slots.contextEngine` to `"legacy"` or another engine id.
+
 ```json
 {
   "plugins": {

plugins/openclaw/hook-shim/HOOK.md

@@ -0,0 +1,21 @@
+---
+name: headroom-link-shim
+description: "No-op hook shim so local plugin source paths are also valid OpenClaw hook-pack paths."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🪝",
+        "events": ["command"],
+      },
+  }
+---
+
+# Headroom Link Shim
+
+This hook intentionally does nothing.
+
+OpenClaw currently falls back to validating local plugin paths as hook packs when a
+plugin install cannot proceed, such as when the plugin is already installed.
+Including this no-op hook keeps `--link` installs from reporting a misleading
+`package.json missing openclaw.hooks` error for valid Headroom plugin paths.

plugins/openclaw/hook-shim/handler.js

@@ -0,0 +1,3 @@
+export default async function headroomLinkShim() {
+  return undefined;
+}

plugins/openclaw/openclaw.plugin.json

@@ -1,5 +1,6 @@
 {
   "id": "headroom",
+  "kind": "context-engine",
   "uiHints": {
     "proxyUrl": {
       "label": "Proxy URL",

plugins/openclaw/package.json

@@ -7,11 +7,12 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "hook-shim",
     "openclaw.plugin.json",
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node prepare-dist.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
@@ -34,12 +35,9 @@
     "vitest": "^2.0.0"
   },
   "openclaw": {
-    "hooks": {
-      "contextEngine": "dist/index.js",
-      "tools": [
-        "dist/index.js"
-      ]
-    },
+    "hooks": [
+      "./hook-shim"
+    ],
     "extensions": [
       "./dist/index.js"
     ],

plugins/openclaw/prepare-dist.mjs

@@ -0,0 +1,56 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = __dirname;
+const distDir = path.join(rootDir, "dist");
+
+const rootPackage = JSON.parse(
+  await fs.readFile(path.join(rootDir, "package.json"), "utf8"),
+);
+
+const distPackage = {
+  name: rootPackage.name,
+  version: rootPackage.version,
+  description: rootPackage.description,
+  type: rootPackage.type,
+  main: "./index.js",
+  types: "./index.d.ts",
+  license: rootPackage.license,
+  dependencies: rootPackage.dependencies,
+  peerDependencies: rootPackage.peerDependencies,
+  peerDependenciesMeta: rootPackage.peerDependenciesMeta,
+  openclaw: {
+    hooks: ["./hook-shim"],
+    extensions: ["./index.js"],
+    capabilities: rootPackage.openclaw?.capabilities ?? {},
+  },
+};
+
+await fs.mkdir(distDir, { recursive: true });
+await fs.writeFile(
+  path.join(distDir, "package.json"),
+  `${JSON.stringify(distPackage, null, 2)}\n`,
+  "utf8",
+);
+
+await Promise.all([
+  fs.copyFile(
+    path.join(rootDir, "openclaw.plugin.json"),
+    path.join(distDir, "openclaw.plugin.json"),
+  ),
+  fs.copyFile(path.join(rootDir, "README.md"), path.join(distDir, "README.md")),
+  fs.mkdir(path.join(distDir, "hook-shim"), { recursive: true }),
+]);
+
+await Promise.all([
+  fs.copyFile(
+    path.join(rootDir, "hook-shim", "HOOK.md"),
+    path.join(distDir, "hook-shim", "HOOK.md"),
+  ),
+  fs.copyFile(
+    path.join(rootDir, "hook-shim", "handler.js"),
+    path.join(distDir, "hook-shim", "handler.js"),
+  ),
+]);