@vellumai/assistant 0.6.4 → 0.6.6

package/src/hooks/cli.ts

@@ -1,253 +0,0 @@
-import { chmodSync, cpSync, readFileSync, rmSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
-
-import { Command } from "commander";
-
-import { pathExists } from "../util/fs.js";
-import { getCliLogger } from "../util/logger.js";
-import { getWorkspaceHooksDir } from "../util/platform.js";
-import { ensureHookInConfig, removeHook, setHookEnabled } from "./config.js";
-import { discoverHooks, isValidInstallManifest } from "./discovery.js";
-
-const log = getCliLogger("hooks");
-
-export function registerHooksCommand(program: Command): void {
-  const hooks = program.command("hooks").description("Manage hooks");
-
-  hooks.addHelpText(
-    "after",
-    `
-Hooks are user-installed scripts that run in response to assistant lifecycle
-events (e.g. tool invocations, message sends). Each hook is a directory
-containing a hook.json manifest and a script file. Hooks are stored in
-$VELLUM_WORKSPACE_DIR/hooks/ and must be explicitly enabled after installation.
-
-Examples:
-  $ assistant hooks list
-  $ assistant hooks install ./my-hook
-  $ assistant hooks enable my-hook
-  $ assistant hooks disable my-hook`,
-  );
-
-  hooks
-    .command("list")
-    .description("List all installed hooks")
-    .addHelpText(
-      "after",
-      `
-Displays a table of all installed hooks with their name, subscribed events,
-enabled status, and version.
-
-Examples:
-  $ assistant hooks list`,
-    )
-    .action(() => {
-      const discovered = discoverHooks();
-      if (discovered.length === 0) {
-        log.info("No hooks installed");
-        return;
-      }
-
-      const nameW = 24;
-      const eventsW = 24;
-      const enabledW = 10;
-      log.info(
-        "Name".padEnd(nameW) +
-          "Events".padEnd(eventsW) +
-          "Enabled".padEnd(enabledW) +
-          "Version",
-      );
-      log.info("-".repeat(nameW + eventsW + enabledW + 10));
-
-      for (const hook of discovered) {
-        const events = hook.manifest.events.join(", ");
-        const eventsTrunc =
-          events.length > eventsW - 2
-            ? events.slice(0, eventsW - 4) + ".."
-            : events;
-        log.info(
-          hook.name.slice(0, nameW - 2).padEnd(nameW) +
-            eventsTrunc.padEnd(eventsW) +
-            (hook.enabled ? "yes" : "no").padEnd(enabledW) +
-            (hook.manifest.version ?? "-"),
-        );
-      }
-    });
-
-  hooks
-    .command("enable <name>")
-    .description("Enable a hook")
-    .addHelpText(
-      "after",
-      `
-Arguments:
-  name   Hook name as shown by 'assistant hooks list'
-
-Enables a previously installed hook so it runs on matching events.
-
-Examples:
-  $ assistant hooks enable my-hook`,
-    )
-    .action((name: string) => {
-      const discovered = discoverHooks();
-      const hook = discovered.find((h) => h.name === name);
-      if (!hook) {
-        log.error(`Hook not found: ${name}`);
-        process.exit(1);
-      }
-      setHookEnabled(name, true);
-      log.info(`Enabled hook: ${name}`);
-    });
-
-  hooks
-    .command("disable <name>")
-    .description("Disable a hook")
-    .addHelpText(
-      "after",
-      `
-Arguments:
-  name   Hook name as shown by 'assistant hooks list'
-
-Disables a hook so it no longer runs on events. The hook remains installed
-and can be re-enabled later.
-
-Examples:
-  $ assistant hooks disable my-hook`,
-    )
-    .action((name: string) => {
-      const discovered = discoverHooks();
-      const hook = discovered.find((h) => h.name === name);
-      if (!hook) {
-        log.error(`Hook not found: ${name}`);
-        process.exit(1);
-      }
-      setHookEnabled(name, false);
-      log.info(`Disabled hook: ${name}`);
-    });
-
-  hooks
-    .command("install <path>")
-    .description("Install a hook from a directory")
-    .addHelpText(
-      "after",
-      `
-Arguments:
-  path   Path to a directory containing a hook.json manifest and a script file.
-         The manifest must have name, script, description, version, and at
-         least one valid event.
-
-Copies the hook directory into $VELLUM_WORKSPACE_DIR/hooks/<name>/ and registers it as
-disabled by default. Run 'assistant hooks enable <name>' to activate.
-
-Examples:
-  $ assistant hooks install ./my-hook
-  $ assistant hooks install /path/to/custom-hook`,
-    )
-    .action((hookPath: string) => {
-      const srcDir = resolve(hookPath);
-      if (!pathExists(srcDir)) {
-        log.error(`Directory not found: ${srcDir}`);
-        process.exit(1);
-      }
-
-      const manifestPath = join(srcDir, "hook.json");
-      if (!pathExists(manifestPath)) {
-        log.error(`No hook.json found in ${srcDir}`);
-        process.exit(1);
-      }
-
-      let manifest: unknown;
-      try {
-        manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-      } catch {
-        log.error(`Failed to parse hook.json in ${srcDir}`);
-        process.exit(1);
-      }
-
-      if (!isValidInstallManifest(manifest)) {
-        log.error(
-          "Invalid hook.json: must have a non-empty name, script, description (string), version (string), and at least one valid event",
-        );
-        process.exit(1);
-      }
-
-      const hooksDir = getWorkspaceHooksDir();
-      const resolvedHooksDir = resolve(hooksDir);
-      const targetDir = resolve(join(hooksDir, manifest.name));
-      if (!targetDir.startsWith(resolvedHooksDir + sep)) {
-        log.error(
-          `Invalid hook name: "${manifest.name}" would escape the hooks directory`,
-        );
-        process.exit(1);
-      }
-
-      const scriptPath = resolve(join(targetDir, manifest.script));
-      if (!scriptPath.startsWith(targetDir + sep)) {
-        log.error(
-          `Invalid hook script: "${manifest.script}" would escape the hook directory`,
-        );
-        process.exit(1);
-      }
-
-      if (pathExists(targetDir)) {
-        log.error(`Hook already installed: ${manifest.name}`);
-        process.exit(1);
-      }
-
-      cpSync(srcDir, targetDir, { recursive: true });
-
-      // Make script executable
-      if (pathExists(scriptPath)) {
-        chmodSync(scriptPath, 0o755);
-      }
-
-      ensureHookInConfig(manifest.name, { enabled: false });
-      log.info(`Installed hook: ${manifest.name} (disabled by default)`);
-    });
-
-  hooks
-    .command("remove <name>")
-    .description("Remove an installed hook")
-    .addHelpText(
-      "after",
-      `
-Arguments:
-  name   Hook name as shown by 'assistant hooks list'
-
-Permanently deletes the hook directory and removes it from configuration.
-Prompts for confirmation before proceeding.
-
-Examples:
-  $ assistant hooks remove my-hook`,
-    )
-    .action(async (name: string) => {
-      const discovered = discoverHooks();
-      const hook = discovered.find((h) => h.name === name);
-      if (!hook) {
-        log.error(`Hook not found: ${name}`);
-        process.exit(1);
-      }
-
-      const readline = await import("node:readline");
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-      const answer = await new Promise<string>((resolve) => {
-        rl.question(
-          `Remove hook "${name}" and delete its files? (y/N) `,
-          resolve,
-        );
-      });
-      rl.close();
-
-      if (answer.toLowerCase() !== "y") {
-        log.info("Cancelled");
-        return;
-      }
-
-      rmSync(hook.dir, { recursive: true, force: true });
-      removeHook(name);
-      log.info(`Removed hook: ${name}`);
-    });
-}

package/src/hooks/config.ts

@@ -1,100 +0,0 @@
-import { writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-import { ensureDir, readTextFileSync } from "../util/fs.js";
-import { getLogger } from "../util/logger.js";
-import { getWorkspaceHooksDir } from "../util/platform.js";
-import type { HookConfig, HookConfigEntry, HookManifest } from "./types.js";
-
-const log = getLogger("hooks-config");
-
-const HOOKS_CONFIG_VERSION = 1;
-
-function getConfigPath(): string {
-  return join(getWorkspaceHooksDir(), "config.json");
-}
-
-export function loadHooksConfig(): HookConfig {
-  const configPath = getConfigPath();
-  const raw = readTextFileSync(configPath);
-  if (raw == null) {
-    return { version: HOOKS_CONFIG_VERSION, hooks: {} };
-  }
-
-  try {
-    const parsed = JSON.parse(raw) as HookConfig;
-    if (
-      typeof parsed.version !== "number" ||
-      typeof parsed.hooks !== "object" ||
-      parsed.hooks == null
-    ) {
-      log.warn({ configPath }, "Invalid hooks config, using defaults");
-      return { version: HOOKS_CONFIG_VERSION, hooks: {} };
-    }
-    return parsed;
-  } catch (err) {
-    log.warn(
-      { err, configPath },
-      "Failed to read hooks config, using defaults",
-    );
-    return { version: HOOKS_CONFIG_VERSION, hooks: {} };
-  }
-}
-
-export function saveHooksConfig(config: HookConfig): void {
-  const configPath = getConfigPath();
-  ensureDir(dirname(configPath));
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
-}
-
-export function isHookEnabled(hookName: string): boolean {
-  const config = loadHooksConfig();
-  return config.hooks[hookName]?.enabled ?? false;
-}
-
-export function setHookEnabled(hookName: string, enabled: boolean): void {
-  const config = loadHooksConfig();
-  config.hooks[hookName] = { ...config.hooks[hookName], enabled };
-  saveHooksConfig(config);
-}
-
-export function ensureHookInConfig(
-  hookName: string,
-  entry: HookConfigEntry,
-): void {
-  const config = loadHooksConfig();
-  if (hookName in config.hooks) return;
-  config.hooks[hookName] = entry;
-  saveHooksConfig(config);
-}
-
-export function removeHook(hookName: string): void {
-  const config = loadHooksConfig();
-  delete config.hooks[hookName];
-  saveHooksConfig(config);
-}
-
-/**
- * Get merged settings for a hook. Manifest defaults are used as the base,
- * then user overrides from config.json are applied on top.
- */
-export function getHookSettings(
-  hookName: string,
-  manifest: HookManifest,
-): Record<string, unknown> {
-  // Start with defaults from manifest schema
-  const defaults: Record<string, unknown> = {};
-  if (manifest.settingsSchema) {
-    for (const [key, schema] of Object.entries(manifest.settingsSchema)) {
-      if (schema.default !== undefined) {
-        defaults[key] = schema.default;
-      }
-    }
-  }
-
-  // Merge user overrides from config
-  const config = loadHooksConfig();
-  const userSettings = config.hooks[hookName]?.settings ?? {};
-
-  return { ...defaults, ...userSettings };
-}

package/src/hooks/discovery.ts

@@ -1,135 +0,0 @@
-import { type Dirent, readdirSync, readFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-
-import { pathExists } from "../util/fs.js";
-import { getLogger } from "../util/logger.js";
-import { getWorkspaceHooksDir } from "../util/platform.js";
-import { loadHooksConfig } from "./config.js";
-import type { DiscoveredHook, HookManifest } from "./types.js";
-
-const log = getLogger("hooks-discovery");
-
-const VALID_EVENTS = new Set<string>([
-  "daemon-start",
-  "daemon-stop",
-  "conversation-start",
-  "conversation-end",
-  // Legacy aliases — existing user hooks may still reference the old names.
-  "session-start",
-  "session-end",
-  "pre-llm-call",
-  "post-llm-call",
-  "pre-tool-execute",
-  "post-tool-execute",
-  "permission-request",
-  "permission-resolve",
-  "pre-message",
-  "post-message",
-  "on-error",
-]);
-
-/**
- * Validates the core manifest fields required for discovery.
- * `description` and `version` are optional here so that legacy hook manifests
- * (created before those fields were added) continue to be discovered.
- */
-export function isValidManifest(manifest: unknown): manifest is HookManifest {
-  if (typeof manifest !== "object" || manifest == null) return false;
-  const m = manifest as Record<string, unknown>;
-  if (typeof m.name !== "string" || !m.name) return false;
-  if (typeof m.script !== "string" || !m.script) return false;
-  if (!Array.isArray(m.events) || m.events.length === 0) return false;
-  for (const e of m.events) {
-    if (typeof e !== "string" || !VALID_EVENTS.has(e)) return false;
-  }
-  // Optional fields: allow if present but must be strings
-  if (m.description !== undefined && typeof m.description !== "string")
-    return false;
-  if (m.version !== undefined && typeof m.version !== "string") return false;
-  return true;
-}
-
-/**
- * Stricter validation for installing new hooks.
- * Requires `description` and `version` in addition to the core fields.
- */
-export function isValidInstallManifest(
-  manifest: unknown,
-): manifest is HookManifest & { description: string; version: string } {
-  if (!isValidManifest(manifest)) return false;
-  if (typeof manifest.description !== "string" || !manifest.description)
-    return false;
-  if (typeof manifest.version !== "string" || !manifest.version) return false;
-  return true;
-}
-
-export function discoverHooks(hooksDir?: string): DiscoveredHook[] {
-  const dir = hooksDir ?? getWorkspaceHooksDir();
-  if (!pathExists(dir)) return [];
-
-  const config = loadHooksConfig();
-  const hooks: DiscoveredHook[] = [];
-
-  let entries: Dirent[];
-  try {
-    entries = readdirSync(dir, { withFileTypes: true }) as Dirent[];
-  } catch (err) {
-    log.warn({ err, dir }, "Failed to read hooks directory");
-    return [];
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const hookDir = join(dir, entry.name);
-    const manifestPath = join(hookDir, "hook.json");
-    if (!pathExists(manifestPath)) continue;
-
-    let manifest: unknown;
-    try {
-      manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-    } catch (err) {
-      log.warn({ err, hookDir }, "Failed to parse hook manifest");
-      continue;
-    }
-
-    if (!isValidManifest(manifest)) {
-      log.warn({ hookDir }, "Invalid hook manifest, skipping");
-      continue;
-    }
-
-    const scriptPath = resolve(hookDir, manifest.script);
-    const rel = relative(hookDir, scriptPath);
-    // Normalize backslashes so Windows-style traversal (e.g. `..\\..\\evil.js`) is
-    // also caught. This project targets macOS, but we check for defense in depth.
-    const normalizedRel = rel.replaceAll("\\", "/");
-    if (
-      normalizedRel.startsWith("../") ||
-      normalizedRel === ".." ||
-      resolve(hookDir, rel) !== scriptPath
-    ) {
-      log.warn(
-        { hookDir, script: manifest.script },
-        "Hook script path traversal detected, skipping",
-      );
-      continue;
-    }
-    if (!pathExists(scriptPath)) {
-      log.warn(
-        { hookDir, script: manifest.script },
-        "Hook script not found, skipping",
-      );
-      continue;
-    }
-
-    hooks.push({
-      name: entry.name,
-      dir: hookDir,
-      manifest,
-      scriptPath,
-      enabled: config.hooks[entry.name]?.enabled ?? false,
-    });
-  }
-
-  return hooks.sort((a, b) => a.name.localeCompare(b.name));
-}

package/src/hooks/manager.ts

@@ -1,179 +0,0 @@
-import { type FSWatcher, watch } from "node:fs";
-
-import { getIsContainerized } from "../config/env-registry.js";
-import { Debouncer } from "../util/debounce.js";
-import { pathExists } from "../util/fs.js";
-import { getLogger } from "../util/logger.js";
-import { getWorkspaceHooksDir } from "../util/platform.js";
-import { discoverHooks } from "./discovery.js";
-import { runHookScript } from "./runner.js";
-import type {
-  DiscoveredHook,
-  HookEventData,
-  HookEventName,
-  HookTriggerResult,
-} from "./types.js";
-
-const log = getLogger("hooks-manager");
-
-/**
- * Legacy event name aliases so existing user hooks that reference the old
- * session-based names still fire when the corresponding conversation event
- * is triggered.
- */
-const LEGACY_EVENT_ALIASES: Partial<Record<HookEventName, HookEventName[]>> = {
-  "conversation-start": ["session-start"],
-  "conversation-end": ["session-end"],
-};
-
-export class HookManager {
-  private hooks: DiscoveredHook[] = [];
-  private eventIndex = new Map<HookEventName, DiscoveredHook[]>();
-  private watcher: FSWatcher | null = null;
-  private readonly debouncer = new Debouncer(500);
-
-  initialize(): void {
-    if (getIsContainerized()) {
-      log.info("Hooks disabled in containerized mode");
-      return;
-    }
-    this.hooks = discoverHooks();
-    this.buildEventIndex();
-    const enabled = this.hooks.filter((h) => h.enabled).length;
-    if (this.hooks.length > 0) {
-      log.info({ enabled, total: this.hooks.length }, "Hooks discovered");
-    }
-  }
-
-  private buildEventIndex(): void {
-    this.eventIndex.clear();
-    for (const hook of this.hooks) {
-      if (!hook.enabled) continue;
-      for (const event of hook.manifest.events) {
-        const list = this.eventIndex.get(event) ?? [];
-        list.push(hook);
-        this.eventIndex.set(event, list);
-      }
-    }
-    // Sort alphabetically by name for deterministic ordering
-    for (const [, list] of this.eventIndex) {
-      list.sort((a, b) => a.name.localeCompare(b.name));
-    }
-  }
-
-  async trigger(
-    event: HookEventName,
-    data: Record<string, unknown>,
-  ): Promise<HookTriggerResult> {
-    // Collect hooks registered under the canonical event name and any
-    // legacy aliases (e.g. session-start -> conversation-start).
-    const primaryHooks = this.eventIndex.get(event) ?? [];
-    const legacyAliases = LEGACY_EVENT_ALIASES[event] ?? [];
-    const aliasHooks = legacyAliases.flatMap(
-      (alias) => this.eventIndex.get(alias) ?? [],
-    );
-    // Deduplicate in case a hook subscribes to both old and new names.
-    const seen = new Set<string>();
-    const hooks: DiscoveredHook[] = [];
-    for (const h of [...primaryHooks, ...aliasHooks]) {
-      if (!seen.has(h.name)) {
-        seen.add(h.name);
-        hooks.push(h);
-      }
-    }
-    if (hooks.length === 0) return { blocked: false };
-
-    const isPreEvent = event.startsWith("pre-");
-    const eventData: HookEventData = { ...data, event };
-
-    for (const hook of hooks) {
-      try {
-        const result = await runHookScript(hook, eventData);
-        if (result.exitCode != null && result.exitCode !== 0) {
-          // Blocking hooks on pre-* events cancel the action
-          if (isPreEvent && hook.manifest.blocking) {
-            log.info(
-              { hook: hook.name, event, exitCode: result.exitCode },
-              "Blocking hook rejected action",
-            );
-            return { blocked: true, blockedBy: hook.name };
-          }
-          log.warn(
-            { hook: hook.name, event, exitCode: result.exitCode },
-            "Hook exited with non-zero code",
-          );
-        }
-      } catch (err) {
-        log.warn({ err, hook: hook.name, event }, "Hook execution failed");
-      }
-    }
-
-    return { blocked: false };
-  }
-
-  reload(): void {
-    if (getIsContainerized()) return;
-    this.hooks = discoverHooks();
-    this.buildEventIndex();
-    const enabled = this.hooks.filter((h) => h.enabled).length;
-    log.info({ enabled, total: this.hooks.length }, "Hooks reloaded");
-  }
-
-  watch(): void {
-    if (getIsContainerized()) return;
-    const hooksDir = getWorkspaceHooksDir();
-    if (!pathExists(hooksDir)) return;
-
-    this.stopWatching();
-
-    try {
-      this.watcher = watch(
-        hooksDir,
-        { recursive: true },
-        (_eventType, filename) => {
-          this.debouncer.schedule(() => {
-            log.info(
-              { filename: String(filename ?? "") },
-              "Hooks directory changed, reloading",
-            );
-            this.reload();
-          });
-        },
-      );
-      log.info({ dir: hooksDir }, "Watching hooks directory for changes");
-    } catch (err) {
-      log.warn(
-        { err, dir: hooksDir },
-        "Failed to watch hooks directory. Hot-reload will be unavailable.",
-      );
-    }
-  }
-
-  stopWatching(): void {
-    this.debouncer.cancel();
-    if (this.watcher) {
-      this.watcher.close();
-      this.watcher = null;
-    }
-  }
-
-  getDiscoveredHooks(): DiscoveredHook[] {
-    return [...this.hooks];
-  }
-}
-
-let instance: HookManager | null = null;
-
-export function getHookManager(): HookManager {
-  if (!instance) {
-    instance = new HookManager();
-    instance.initialize();
-  }
-  return instance;
-}
-
-/** Reset the singleton (for testing) */
-export function resetHookManager(): void {
-  instance?.stopWatching();
-  instance = null;
-}