fix(doctor): resolve bare relative hook scripts and PowerShell -File operands

Author: ScriptedAlchemy

docs/diagnostics.md

@@ -712,7 +712,7 @@ that registration statically and never writes `~/.cursor/hooks.json`.
 
 | Code | Severity | Meaning | Recovery |
 | --- | --- | --- | --- |
-| `AB7321` | info / error | Info: an installed `.cursor-plugin/plugin.json` plugin registers plugin-scoped hooks (events and command count listed) and every `${CURSOR_PLUGIN_ROOT}`-relative script exists (`hooks.state = registered`). Error: the declared hooks file is missing (`missing`), is not a `{ version, hooks: { <event>: [{ command }] } }` document, or a referenced script is absent (`stale`). | Reinstall the plugin from a bundle whose emitted hooks document and scripts are intact. |
+| `AB7321` | info / error | Info: an installed `.cursor-plugin/plugin.json` plugin registers plugin-scoped hooks (events and command count listed) and the script each command executes — `${CURSOR_PLUGIN_ROOT}/…` or any relative path, including an interpreter's entry operand — exists under the plugin root (`hooks.state = registered`). Error: the declared hooks file is missing (`missing`), is not a `{ version, hooks: { <event>: [{ command }] } }` document, or an executed script is absent (`stale`). | Reinstall the plugin from a bundle whose emitted hooks document and scripts are intact. |
 | `AB7322` | warning | `~/.cursor/hooks.json` registers a command that points into an installed plugin directory (Cursor would deliver that hook twice), or the file is not a valid hooks document. | Remove the plugin-pointing entries or repair the file; manifest registration alone is sufficient. |
 | `AB7323` | info / warning / error | A staged marketplace repository under `~/.cursor/agent-bundle/marketplaces/<name>` (from `install cursor --mode marketplace`) is imported by Cursor (matching plugin under `~/.cursor/plugins/cache`; info, `registered`), still awaiting the Customize "Add Plugins from Local Repository" step (warning, `unregistered`), or incomplete (error, `corrupt`: manifests missing or failing the pinned schemas, no resolvable Git HEAD, HEAD naming a commit object that does not exist, or a working tree that differs from committed HEAD — verified read-only through `git cat-file -e` / `git --no-optional-locks status` when `git` is available). | Complete the Customize import, use `--mode local`, or remove the staged directory and rerun the installer. |
 

packages/agent-bundle/src/install/cursor-hooks-registration.ts

@@ -142,39 +142,58 @@ const inlineSourceOptions = new Set(['--eval', '--print', '-Command', '-c', '-co
 /** Interpreter options that consume the next token (a path or value), which is therefore not the entry script. */
 const valueOptions = new Set([
   '--conditions', '--define', '--env-file', '--experimental-loader', '--import', '--input-type', '--loader',
-  '--preload', '--require', '--stack-trace-limit', '--title', '-C', '-ExecutionPolicy', '-File', '-I', '-W', '-X',
+  '--preload', '--require', '--stack-trace-limit', '--title', '-C', '-ExecutionPolicy', '-I', '-W', '-X',
   '-d', '-o', '-r',
 ]);
 
+const powerShell = new Set(['powershell', 'pwsh']);
+
+interface ExecutedPath {
+  /** `executable` is the command word itself (PATH lookup unless it names a path); `operand` is a script argument. */
+  readonly kind: 'executable' | 'operand';
+  readonly token: string;
+}
+
 /**
  * The file a hook command executes: the executable token itself, or, for a known interpreter, the entry-script
- * operand after skipping options (value-taking options consume their operand; `--opt=value` consumes nothing).
- * `undefined` when the interpreter runs inline source (`node -e`, `sh -c`, `python -m`) or has no operand.
- * Other arguments (`--output ./state/result.json`) are runtime inputs/outputs, never the executed file.
+ * operand after skipping options (value-taking options consume their operand; `--opt=value` consumes nothing;
+ * PowerShell's `-File <path>` selects the script). `undefined` when the interpreter runs inline source
+ * (`node -e`, `sh -c`, `python -m`) or has no operand. Other arguments (`--output ./state/result.json`) are
+ * runtime inputs/outputs, never the executed file.
  */
-const executedPath = (tokens: readonly string[]): string | undefined => {
+const executedPath = (tokens: readonly string[]): ExecutedPath | undefined => {
   const [executable, ...operands] = tokens;
   if (executable === undefined) return undefined;
   const interpreter = executable.replace(/^.*[\\/]/u, '').replace(/\.exe$/iu, '');
-  if (!scriptInterpreters.has(interpreter)) return executable;
+  if (!scriptInterpreters.has(interpreter)) return { kind: 'executable', token: executable };
+  const operand = (token: string | undefined): ExecutedPath | undefined =>
+    token === undefined ? undefined : { kind: 'operand', token };
   for (let index = 0; index < operands.length; index += 1) {
     const token = operands[index] ?? '';
-    if (!token.startsWith('-') || token === '-') return token;
+    if (!token.startsWith('-') || token === '-') return operand(token);
+    if (powerShell.has(interpreter) && /^-f(?:ile)?$/iu.test(token)) return operand(operands[index + 1]);
     if (inlineSourceOptions.has(token)) return undefined;
     if (valueOptions.has(token) && !token.includes('=')) index += 1;
   }
   return undefined;
 };
 
-const pluginRelativePath = (token: string, pluginDirectory: string): string | undefined => {
+/**
+ * Where a hook's executed file lives under the plugin root: `${CURSOR_PLUGIN_ROOT}/...` spellings, and any other
+ * non-absolute path (plugin hooks run from the plugin root, and the pinned schema resolves relative paths against
+ * the hook source root). A bare executable word without a separator is a PATH lookup, not a plugin file.
+ */
+const pluginRelativePath = (executed: ExecutedPath, pluginDirectory: string): string | undefined => {
+  const { kind, token } = executed;
   if (token.startsWith(`${pluginRootToken}/`)) return join(pluginDirectory, token.slice(pluginRootToken.length + 1));
-  if (token.startsWith('./') || token.startsWith('.\\')) return join(pluginDirectory, token);
-  return undefined;
+  if (token.startsWith('${') || token.startsWith('~') || isAbsolute(token) || /^[A-Za-z]:[\\/]/u.test(token)) return undefined;
+  if (kind === 'executable' && !/[\\/]/u.test(token)) return undefined;
+  return join(pluginDirectory, token.replaceAll('\\', '/'));
 };
 
 /**
- * The plugin-root file a hook command executes (`${CURSOR_PLUGIN_ROOT}/...` or `./`-relative, since plugin
- * hooks run from the plugin root); empty when the executed file lives elsewhere or the command runs inline source.
+ * The plugin-root file a hook command executes; empty when the executed file lives elsewhere (absolute, `~`, or a
+ * PATH lookup) or the command runs inline source.
  */
 const pluginRelativeScripts = (command: string, pluginDirectory: string): readonly string[] => {
   const executed = executedPath(shellWords(command));
@@ -240,13 +259,15 @@ const userHookDuplicates = async (
   // ./plugins/local/foo/state.json`) does not deliver that plugin's hook. `insidePlugin` matches on a path
   // component boundary so `plugins/local/foo` does not claim hooks aimed at `plugins/local/foo-tools`.
   const pointsIntoPlugin = (command: string): boolean => {
-    const token = executedPath(shellWords(command));
-    if (token === undefined || token.length === 0) return false;
+    const executed = executedPath(shellWords(command));
+    if (executed === undefined || executed.token.length === 0) return false;
+    const { kind, token } = executed;
     if (token.startsWith('~/')) return insidePlugin(resolve(home, token.slice(2)));
-    // Relative spellings may use either separator (`.\plugins\local\foo` on Windows); normalise before resolving.
-    if (/^\.\.?[\\/]/u.test(token)) return insidePlugin(resolve(userHookCwd, token.replaceAll('\\', '/')));
     if (isAbsolute(token)) return insidePlugin(resolve(token));
-    return false;
+    // A bare executable word is a PATH lookup; any other relative spelling (either separator, e.g.
+    // `.\plugins\local\foo` on Windows) resolves against ~/.cursor.
+    if (kind === 'executable' && !/[\\/]/u.test(token)) return false;
+    return insidePlugin(resolve(userHookCwd, token.replaceAll('\\', '/')));
   };
   const duplicates = parsed.commands.filter(pointsIntoPlugin);
   if (duplicates.length === 0) return { diagnostics: Object.freeze([]), duplicates: Object.freeze([]) };

packages/agent-bundle/tests/doctor.test.ts

@@ -1589,6 +1589,18 @@ it('proves plugin-scoped Cursor hook registration and flags stale, missing, and
     expect(hostReport(optionOperand, 'cursor').inventory.findings[0]?.hooks).toMatchObject({ state: 'stale' });
     expect(hookDiagnostics(optionOperand)[0]?.message).toContain(join(pluginRoot, 'hooks/gone.mjs'));
 
+    // Bare relative operands resolve against the plugin root too (pinned schema: relative to the hook source root),
+    // and PowerShell's -File operand is the entry script.
+    for (const command of ['node hooks/gone.mjs', 'pwsh -NoProfile -File hooks/gone.mjs', 'hooks/gone.mjs --flag']) {
+      await writeJson(join(pluginRoot, 'hooks/hooks.json'), { hooks: { stop: [{ command }] }, version: 1 });
+      const bareRelative = await doctor();
+      expect(hostReport(bareRelative, 'cursor').inventory.findings[0]?.hooks).toMatchObject({ state: 'stale' });
+      expect(hookDiagnostics(bareRelative)[0]?.message).toContain(join(pluginRoot, 'hooks/gone.mjs'));
+    }
+    // A bare executable word is a PATH lookup, not a plugin file.
+    await writeJson(join(pluginRoot, 'hooks/hooks.json'), { hooks: { stop: [{ command: 'gone-tool --flag hooks/gone.mjs' }] }, version: 1 });
+    expect(hostReport(await doctor(), 'cursor').inventory.findings[0]?.hooks).toMatchObject({ commands: 1, state: 'registered' });
+
     // Inline source runs no script file, so there is nothing under the plugin root to probe.
     await writeJson(join(pluginRoot, 'hooks/hooks.json'), {
       hooks: { stop: [{ command: 'node -e "process.exit(0)" ./hooks/gone.mjs' }] },