feat: sync Node Auggie hook integration

sdks/node/src/plugins/augment-contract.ts

@@ -0,0 +1,316 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const AGENT_KEY = 'augment';
+export const GUARD_SCRIPT = 'guard.js';
+export const AUDIT_SCRIPT = 'hook.js';
+export const HOOK_TIMEOUT_MILLISECONDS = 10_000;
+
+const WRAPPER_EXTENSION = process.platform === 'win32' ? '.cmd' : '.sh';
+export const GUARD_WRAPPER = `augment-guard${WRAPPER_EXTENSION}`;
+export const AUDIT_WRAPPER = `augment-hook${WRAPPER_EXTENSION}`;
+
+const TOOL_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+const SESSION_EVENTS = new Set([
+  'Stop',
+  'SessionStart',
+  'SessionEnd',
+  'Notification',
+  'PromptSubmit',
+]);
+
+export type JsonObject = Record<string, unknown>;
+
+export interface AugmentHandler extends JsonObject {
+  readonly type: 'command';
+  readonly command: string;
+  readonly args?: string[];
+  readonly timeout?: number;
+}
+
+export interface AugmentGroup extends JsonObject {
+  readonly matcher?: string;
+  readonly hooks: AugmentHandler[];
+}
+
+export type AugmentHooks = Record<string, AugmentGroup[]>;
+
+export interface AugmentDocument {
+  readonly exists: boolean;
+  readonly configPath: string;
+  readonly root: JsonObject;
+  readonly hooks: AugmentHooks;
+}
+
+export interface RuntimeContract {
+  readonly agentId: string;
+  readonly guardPath: string;
+  readonly auditPath: string;
+  readonly guardWrapperPath: string;
+  readonly auditWrapperPath: string;
+}
+
+interface ParsedArgument {
+  readonly value: string;
+  readonly next: number;
+}
+
+export function isObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(value: JsonObject, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function quotePosix(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function quoteWindows(value: string): string {
+  return `"${value.replaceAll('"', '\\"')}"`;
+}
+
+function quoteBatch(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`;
+}
+
+function readWindowsArgument(command: string, start: number): ParsedArgument | undefined {
+  if (command[start] !== '"') return undefined;
+  let value = '';
+  for (let index = start + 1; index < command.length; index += 1) {
+    if (command[index] === '\\' && command[index + 1] === '"') {
+      value += '"';
+      index += 1;
+      continue;
+    }
+    if (command[index] === '"') return { value, next: index + 1 };
+    value += command[index];
+  }
+  return undefined;
+}
+
+const POSIX_APOSTROPHE = `'"'"'`;
+
+function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
+  if (command[start] !== "'") return undefined;
+  let value = '';
+  for (let index = start + 1; index < command.length;) {
+    if (command.startsWith(POSIX_APOSTROPHE, index)) {
+      value += "'";
+      index += POSIX_APOSTROPHE.length;
+      continue;
+    }
+    if (command[index] === "'") return { value, next: index + 1 };
+    value += command[index];
+    index += 1;
+  }
+  return undefined;
+}
+
+function parseWrapperCommand(command: string): string | undefined {
+  const readArgument = process.platform === 'win32' ? readWindowsArgument : readPosixArgument;
+  const parsed = readArgument(command, 0);
+  return parsed?.next === command.length && parsed.value ? parsed.value : undefined;
+}
+
+function samePath(left: string, right: string): boolean {
+  const normalizedLeft = path.resolve(left);
+  const normalizedRight = path.resolve(right);
+  return process.platform === 'win32'
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+function sameAgentId(left: string, right: string): boolean {
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+export function wrapperPaths(agentId: string): {
+  readonly guardPath: string;
+  readonly auditPath: string;
+} {
+  const agentDirectory = path.join(os.homedir(), '.elydora', agentId);
+  return {
+    guardPath: path.join(agentDirectory, GUARD_WRAPPER),
+    auditPath: path.join(agentDirectory, AUDIT_WRAPPER),
+  };
+}
+
+export function buildHandler(wrapperPath: string): AugmentHandler {
+  const quote = process.platform === 'win32' ? quoteWindows : quotePosix;
+  return {
+    type: 'command',
+    command: quote(wrapperPath),
+    timeout: HOOK_TIMEOUT_MILLISECONDS,
+  };
+}
+
+export function buildWrapper(runtimePath: string): string {
+  if (process.platform === 'win32') {
+    return `@echo off\r\n${quoteBatch(process.execPath)} ${quoteBatch(runtimePath)}\r\nexit /b %errorlevel%\r\n`;
+  }
+  return `#!/bin/sh\nexec ${quotePosix(process.execPath)} ${quotePosix(runtimePath)}\n`;
+}
+
+function managedAgentId(handler: AugmentHandler, wrapperName: string): string | undefined {
+  if (handler.type !== 'command'
+    || handler.timeout !== HOOK_TIMEOUT_MILLISECONDS
+    || typeof handler.command !== 'string'
+    || hasOwn(handler, 'args')) return undefined;
+  const wrapperPath = parseWrapperCommand(handler.command);
+  if (!wrapperPath) return undefined;
+  const actualName = path.basename(wrapperPath);
+  const namesMatch = process.platform === 'win32'
+    ? actualName.toLowerCase() === wrapperName.toLowerCase()
+    : actualName === wrapperName;
+  if (!namesMatch) return undefined;
+  const agentDirectory = path.dirname(wrapperPath);
+  if (!samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) return undefined;
+  const agentId = path.basename(agentDirectory);
+  return agentId && agentId !== '.' && agentId !== '..' ? agentId : undefined;
+}
+
+function validateHandler(
+  value: unknown,
+  event: string,
+  groupIndex: number,
+  handlerIndex: number,
+): AugmentHandler {
+  const label = `Auggie settings handler hooks.${event}[${groupIndex}].hooks[${handlerIndex}]`;
+  if (!isObject(value)) throw new Error(`${label} must be an object`);
+  if (value.type !== 'command') throw new Error(`${label} type must be "command"`);
+  if (typeof value.command !== 'string' || value.command.length === 0) {
+    throw new Error(`${label} requires a non-empty command`);
+  }
+  if (value.args !== undefined
+    && (!Array.isArray(value.args) || !value.args.every((argument) => typeof argument === 'string'))) {
+    throw new Error(`${label} args must be an array of strings`);
+  }
+  if (value.timeout !== undefined
+    && (typeof value.timeout !== 'number' || !Number.isFinite(value.timeout) || value.timeout <= 0)) {
+    throw new Error(`${label} timeout must be a positive finite number`);
+  }
+  return value as AugmentHandler;
+}
+
+function validateMetadata(value: unknown, label: string): void {
+  if (!isObject(value)) throw new Error(`${label} metadata must be an object`);
+  for (const key of ['includeConversationData', 'includeMCPMetadata', 'includeUserContext']) {
+    if (value[key] !== undefined && typeof value[key] !== 'boolean') {
+      throw new Error(`${label} metadata.${key} must be a boolean`);
+    }
+  }
+}
+
+function validateGroup(value: unknown, event: string, groupIndex: number): AugmentGroup {
+  const label = `Auggie settings group hooks.${event}[${groupIndex}]`;
+  if (!isObject(value)) throw new Error(`${label} must be an object`);
+  if (SESSION_EVENTS.has(event) && hasOwn(value, 'matcher')) {
+    throw new Error(`${label} matcher is only supported for tool events`);
+  }
+  if (value.matcher !== undefined) {
+    if (typeof value.matcher !== 'string') throw new Error(`${label} matcher must be a string`);
+    try {
+      new RegExp(value.matcher);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`${label} matcher must be a valid regular expression: ${message}`);
+    }
+  }
+  if (value.metadata !== undefined) validateMetadata(value.metadata, label);
+  if (!Array.isArray(value.hooks)) throw new Error(`${label} must contain a hooks array`);
+  const handlers = value.hooks.map(
+    (handler, handlerIndex) => validateHandler(handler, event, groupIndex, handlerIndex),
+  );
+  return { ...value, hooks: handlers } as AugmentGroup;
+}
+
+export function readHooks(root: JsonObject): AugmentHooks {
+  if (root.hooks === undefined) return {};
+  if (!isObject(root.hooks)) throw new Error('Auggie settings field "hooks" must be an object');
+  const hooks: AugmentHooks = {};
+  for (const [event, value] of Object.entries(root.hooks)) {
+    if (!TOOL_EVENTS.has(event) && !SESSION_EVENTS.has(event)) {
+      throw new Error(`Auggie settings field "hooks.${event}" uses an unsupported event`);
+    }
+    if (!Array.isArray(value)) {
+      throw new Error(`Auggie settings field "hooks.${event}" must be an array`);
+    }
+    hooks[event] = value.map((group, index) => validateGroup(group, event, index));
+  }
+  return hooks;
+}
+
+function removeManaged(
+  groups: AugmentGroup[],
+  wrapperName: string,
+  agentId?: string,
+): { readonly groups: AugmentGroup[]; readonly changed: boolean } {
+  let changed = false;
+  const result: AugmentGroup[] = [];
+  for (const group of groups) {
+    let groupChanged = false;
+    const handlers = group.hooks.filter((handler) => {
+      const managedId = managedAgentId(handler, wrapperName);
+      const remove = managedId !== undefined
+        && (agentId === undefined || sameAgentId(managedId, agentId));
+      if (remove) {
+        changed = true;
+        groupChanged = true;
+      }
+      return !remove;
+    });
+    if (!groupChanged) result.push(group);
+    else if (handlers.length > 0) result.push({ ...group, hooks: handlers });
+  }
+  return { groups: result, changed };
+}
+
+export function removeManagedHooks(hooks: AugmentHooks, agentId?: string): {
+  readonly hooks: AugmentHooks;
+  readonly changed: boolean;
+} {
+  const next = { ...hooks };
+  let changed = false;
+  for (const [event, wrapperName] of [
+    ['PreToolUse', GUARD_WRAPPER],
+    ['PostToolUse', AUDIT_WRAPPER],
+  ] as const) {
+    const result = removeManaged(next[event] ?? [], wrapperName, agentId);
+    if (!result.changed) continue;
+    changed = true;
+    if (result.groups.length > 0) next[event] = result.groups;
+    else delete next[event];
+  }
+  return { hooks: next, changed };
+}
+
+function managedIds(groups: AugmentGroup[], wrapperName: string): Set<string> {
+  const ids = new Set<string>();
+  for (const group of groups) {
+    for (const handler of group.hooks) {
+      const agentId = managedAgentId(handler, wrapperName);
+      if (agentId) ids.add(agentId);
+    }
+  }
+  return ids;
+}
+
+export function runtimeContracts(hooks: AugmentHooks): RuntimeContract[] {
+  const guards = managedIds(hooks.PreToolUse ?? [], GUARD_WRAPPER);
+  const audits = managedIds(hooks.PostToolUse ?? [], AUDIT_WRAPPER);
+  const root = path.join(os.homedir(), '.elydora');
+  return [...guards]
+    .filter((agentId) => [...audits].some((auditId) => sameAgentId(auditId, agentId)))
+    .map((agentId) => {
+      const agentDirectory = path.join(root, agentId);
+      return {
+        agentId,
+        guardPath: path.join(agentDirectory, GUARD_SCRIPT),
+        auditPath: path.join(agentDirectory, AUDIT_SCRIPT),
+        guardWrapperPath: path.join(agentDirectory, GUARD_WRAPPER),
+        auditWrapperPath: path.join(agentDirectory, AUDIT_WRAPPER),
+      };
+    });
+}

sdks/node/src/plugins/augment-io.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  AGENT_KEY,
+  type AugmentDocument,
+  type JsonObject,
+  type RuntimeContract,
+  isObject,
+  readHooks,
+} from './augment-contract.js';
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return isObject(error) && error.code === code;
+}
+
+export function resolveConfigPath(): string {
+  return path.join(os.homedir(), '.augment', 'settings.json');
+}
+
+async function readJsonObject(filePath: string, label: string): Promise<JsonObject | undefined> {
+  let raw: string;
+  try {
+    raw = await fsp.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (hasErrorCode(error, 'ENOENT')) return undefined;
+    throw new Error(`Read ${label} at ${filePath}: ${errorMessage(error)}`, {
+      cause: asError(error),
+    });
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Failed to parse ${label} at ${filePath}: ${errorMessage(error)}`, {
+      cause: asError(error),
+    });
+  }
+  if (!isObject(value)) throw new Error(`${label} at ${filePath} must contain a JSON object`);
+  return value;
+}
+
+export async function readConfig(): Promise<AugmentDocument> {
+  const configPath = resolveConfigPath();
+  const root = await readJsonObject(configPath, 'Auggie settings');
+  if (!root) return { exists: false, configPath, root: {}, hooks: {} };
+  return { exists: true, configPath, root, hooks: readHooks(root) };
+}
+
+async function failWrite(
+  handle: FileHandle | undefined,
+  tempPath: string,
+  label: string,
+  cause: unknown,
+): Promise<never> {
+  const errors = [asError(cause)];
+  if (handle) {
+    try {
+      await handle.close();
+    } catch (error) {
+      errors.push(asError(error));
+    }
+  }
+  try {
+    await fsp.unlink(tempPath);
+  } catch (error) {
+    if (!hasErrorCode(error, 'ENOENT')) errors.push(asError(error));
+  }
+  const message = `Write ${label}: ${errorMessage(cause)}`;
+  if (errors.length > 1) throw new AggregateError(errors, message);
+  throw new Error(message, { cause: errors[0] });
+}
+
+async function writeAtomic(
+  filePath: string,
+  contents: string,
+  mode: number,
+  label: string,
+): Promise<void> {
+  const directory = path.dirname(filePath);
+  await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+  let handle: FileHandle | undefined;
+  try {
+    handle = await fsp.open(tempPath, 'wx', mode);
+    await handle.writeFile(contents, 'utf-8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await fsp.rename(tempPath, filePath);
+  } catch (error) {
+    await failWrite(handle, tempPath, `${label} at ${filePath}`, error);
+  }
+}
+
+export async function writeConfig(configPath: string, root: JsonObject): Promise<void> {
+  await writeAtomic(
+    configPath,
+    JSON.stringify(root, null, 2) + '\n',
+    0o600,
+    'Auggie settings',
+  );
+}
+
+export async function writeWrapper(wrapperPath: string, contents: string): Promise<void> {
+  await writeAtomic(wrapperPath, contents, 0o700, 'Auggie hook wrapper');
+}
+
+export async function removeConfig(configPath: string): Promise<void> {
+  try {
+    await fsp.unlink(configPath);
+  } catch (error) {
+    if (hasErrorCode(error, 'ENOENT')) return;
+    throw new Error(`Remove Auggie settings at ${configPath}: ${errorMessage(error)}`, {
+      cause: asError(error),
+    });
+  }
+}
+
+export async function regularFileExists(filePath: string, label: string): Promise<boolean> {
+  try {
+    return (await fsp.stat(filePath)).isFile();
+  } catch (error) {
+    if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTDIR')) return false;
+    throw new Error(`Read ${label} at ${filePath}: ${errorMessage(error)}`, {
+      cause: asError(error),
+    });
+  }
+}
+
+export async function requireRuntime(filePath: string, label: string): Promise<void> {
+  if (!filePath) throw new Error(`${label} path is required`);
+  if (!await regularFileExists(filePath, label)) throw new Error(`${label} is missing: ${filePath}`);
+}
+
+function sameAgentId(left: string, right: string): boolean {
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+export async function runtimeFilesExist(contracts: RuntimeContract[]): Promise<boolean> {
+  const root = path.join(os.homedir(), '.elydora');
+  let entries: Array<{ isDirectory(): boolean; name: string }>;
+  try {
+    entries = await fsp.readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (hasErrorCode(error, 'ENOENT')) return false;
+    throw new Error(`Read Elydora runtime directory at ${root}: ${errorMessage(error)}`, {
+      cause: asError(error),
+    });
+  }
+  for (const contract of contracts) {
+    const directory = entries.find(
+      (item) => item.isDirectory() && sameAgentId(item.name, contract.agentId),
+    );
+    if (!directory) continue;
+    const agentDirectory = path.join(root, directory.name);
+    const runtimeConfigPath = path.join(agentDirectory, 'config.json');
+    const runtimeConfig = await readJsonObject(runtimeConfigPath, 'Elydora runtime config');
+    if (!runtimeConfig || runtimeConfig.agent_name !== AGENT_KEY) continue;
+    const files = [
+      [contract.guardPath, 'Elydora guard runtime'],
+      [contract.auditPath, 'Elydora audit runtime'],
+      [contract.guardWrapperPath, 'Auggie guard wrapper'],
+      [contract.auditWrapperPath, 'Auggie audit wrapper'],
+    ] as const;
+    const existence = await Promise.all(
+      files.map(([filePath, label]) => regularFileExists(filePath, label)),
+    );
+    if (existence.every(Boolean)) return true;
+  }
+  return false;
+}

sdks/node/src/plugins/augment.ts

@@ -0,0 +1,75 @@
+import type { AgentPlugin, InstallConfig, PluginStatus } from './base.js';
+import { SUPPORTED_AGENTS } from './registry.js';
+import {
+  AGENT_KEY,
+  buildHandler,
+  buildWrapper,
+  removeManagedHooks,
+  runtimeContracts,
+  wrapperPaths,
+} from './augment-contract.js';
+import {
+  readConfig,
+  removeConfig,
+  requireRuntime,
+  runtimeFilesExist,
+  writeConfig,
+  writeWrapper,
+} from './augment-io.js';
+
+const entry = SUPPORTED_AGENTS.get(AGENT_KEY)!;
+
+export const augmentPlugin: AgentPlugin = {
+  async install(config: InstallConfig): Promise<void> {
+    if (!config.agentId) throw new Error('agentId is required');
+    const document = await readConfig();
+    await requireRuntime(config.guardScriptPath, 'Elydora guard runtime');
+    await requireRuntime(config.hookScriptPath, 'Elydora audit runtime');
+
+    const wrappers = wrapperPaths(config.agentId);
+    await writeWrapper(wrappers.guardPath, buildWrapper(config.guardScriptPath));
+    await writeWrapper(wrappers.auditPath, buildWrapper(config.hookScriptPath));
+
+    const cleaned = removeManagedHooks(document.hooks).hooks;
+    const hooks = {
+      ...cleaned,
+      PreToolUse: [
+        ...(cleaned.PreToolUse ?? []),
+        { matcher: '.*', hooks: [buildHandler(wrappers.guardPath)] },
+      ],
+      PostToolUse: [
+        ...(cleaned.PostToolUse ?? []),
+        { matcher: '.*', hooks: [buildHandler(wrappers.auditPath)] },
+      ],
+    };
+    await writeConfig(document.configPath, { ...document.root, hooks });
+    console.log('  Auggie: user-level PreToolUse and PostToolUse hooks installed.');
+  },
+
+  async uninstall(agentId?: string): Promise<void> {
+    const document = await readConfig();
+    if (!document.exists) return;
+    const result = removeManagedHooks(document.hooks, agentId);
+    if (!result.changed) return;
+    const root = { ...document.root };
+    if (Object.keys(result.hooks).length > 0) root.hooks = result.hooks;
+    else delete root.hooks;
+    if (Object.keys(root).length === 0) await removeConfig(document.configPath);
+    else await writeConfig(document.configPath, root);
+  },
+
+  async status(): Promise<PluginStatus> {
+    const document = await readConfig();
+    const contracts = runtimeContracts(document.hooks);
+    const hookConfigured = contracts.length > 0;
+    const hookScriptExists = hookConfigured ? await runtimeFilesExist(contracts) : false;
+    return {
+      installed: hookConfigured && hookScriptExists,
+      agentName: AGENT_KEY,
+      displayName: entry.name,
+      hookConfigured,
+      hookScriptExists,
+      configPath: document.configPath,
+    };
+  },
+};

sdks/node/src/plugins/registry.ts

@@ -5,6 +5,7 @@ export interface AgentRegistryEntry {
 }
 
 export const SUPPORTED_AGENTS: ReadonlyMap<string, AgentRegistryEntry> = new Map([
+  ['augment', { name: 'Augment Code CLI', configDir: '~/.augment', configFile: 'settings.json' }],
   ['claudecode', { name: 'Claude Code', configDir: '~/.claude', configFile: 'settings.json' }],
   ['cursor', { name: 'Cursor', configDir: '.cursor', configFile: 'hooks.json' }],
   ['gemini', { name: 'Gemini CLI', configDir: '~/.gemini', configFile: 'settings.json' }],