fix(augment): make hook installation transactional

This commit is contained in:
ZacharyZhang-NY committed 2026-07-20 09:30:36 -04:00
1 parent b59404cd33
commit 323757e43d
12 files changed
+1121 -506

No files matched your search

+33 -2
View File
@@ -1,5 +1,6 @@
import os from 'node:os';
import path from 'node:path';
import { parseStrictJsonObject } from './strict-json.js';
export const AGENT_KEY = 'augment';
export const GUARD_SCRIPT = 'guard.js';
@@ -40,6 +41,13 @@ export interface AugmentDocument {
readonly configPath: string;
readonly root: JsonObject;
readonly hooks: AugmentHooks;
readonly raw?: string;
}
export interface RenderedAugmentDocument {
readonly document: AugmentDocument;
readonly changed: boolean;
readonly next?: string;
}
export interface RuntimeContract {
@@ -126,11 +134,10 @@ function sameAgentId(left: string, right: string): boolean {
return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
}
export function wrapperPaths(agentId: string): {
export function wrapperPaths(agentDirectory: 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),
@@ -242,6 +249,30 @@ export function readHooks(root: JsonObject): AugmentHooks {
return hooks;
}
export function parseAugmentDocument(configPath: string, raw: string): AugmentDocument {
const root = parseStrictJsonObject(raw, `Auggie user settings at ${configPath}`);
return { exists: true, configPath, root, hooks: readHooks(root), raw };
}
export function createAugmentDocument(configPath: string): AugmentDocument {
return { exists: false, configPath, root: {}, hooks: {} };
}
export function renderAugmentDocument(
document: AugmentDocument,
hooks: AugmentHooks,
): RenderedAugmentDocument {
if (!document.exists && Object.keys(hooks).length === 0) {
return { document, changed: false };
}
const root: JsonObject = { ...document.root };
if (Object.keys(hooks).length > 0) root.hooks = hooks;
else delete root.hooks;
if (Object.keys(root).length === 0) return { document, changed: true };
const next = `${JSON.stringify(root, null, 2)}\n`;
return { document, changed: next !== document.raw, next };
}
function removeManaged(
groups: AugmentGroup[],
wrapperName: string,
+85
View File
@@ -0,0 +1,85 @@
import type { InstallConfig } from './base.js';
import {
AGENT_KEY,
AUDIT_SCRIPT,
AUDIT_WRAPPER,
GUARD_SCRIPT,
GUARD_WRAPPER,
buildWrapper,
type RenderedAugmentDocument,
} from './augment-contract.js';
import {
commitManagedInstallation,
managedRuntimePaths,
preflightManagedInstallation,
prepareManagedInstallation,
type ManagedRuntimePaths,
type PreparedManagedInstallation,
type RenameFile,
} from './managed-installation.js';
const DISPLAY_NAME = 'Augment Code CLI';
const SETTINGS_DIRECTORY_LABEL = 'Auggie configuration directory';
const SETTINGS_LABEL = 'Auggie user settings';
export type AugmentRuntimePaths = ManagedRuntimePaths;
export type PreparedAugmentInstallation = PreparedManagedInstallation;
export type { RenameFile };
export function augmentRuntimePaths(config: InstallConfig): AugmentRuntimePaths {
return managedRuntimePaths(config, AGENT_KEY, GUARD_SCRIPT, AUDIT_SCRIPT);
}
export async function preflightAugmentInstallation(
config: InstallConfig,
settingsPath: string,
): Promise<AugmentRuntimePaths> {
return preflightManagedInstallation({
agentKey: AGENT_KEY,
hookLocations: [{ directoryLabel: SETTINGS_DIRECTORY_LABEL, filePath: settingsPath }],
config,
}, GUARD_SCRIPT, AUDIT_SCRIPT);
}
export async function prepareAugmentInstallation(
config: InstallConfig,
rendered: RenderedAugmentDocument,
): Promise<PreparedAugmentInstallation> {
if (!rendered.changed && rendered.document.raw === undefined) {
throw new Error('Auggie hook installation did not produce a settings document');
}
const settingsSource = rendered.next ?? rendered.document.raw;
if (settingsSource === undefined) throw new Error('Auggie hook settings are missing');
const paths = augmentRuntimePaths(config);
return prepareManagedInstallation({
agentKey: AGENT_KEY,
displayName: DISPLAY_NAME,
hookSources: [{
directoryLabel: SETTINGS_DIRECTORY_LABEL,
label: SETTINGS_LABEL,
filePath: rendered.document.configPath,
expectedSource: rendered.document.raw,
source: settingsSource,
}],
runtimeFiles: [{
fileName: GUARD_WRAPPER,
label: 'Auggie guard wrapper',
source: buildWrapper(paths.guardPath),
mode: 0o700,
}, {
fileName: AUDIT_WRAPPER,
label: 'Auggie audit wrapper',
source: buildWrapper(paths.auditPath),
mode: 0o700,
}],
config,
auditOptions: { nativePayload: true },
}, GUARD_SCRIPT, AUDIT_SCRIPT);
}
export async function commitAugmentInstallation(
prepared: PreparedAugmentInstallation,
renameFile?: RenameFile,
): Promise<void> {
await commitManagedInstallation(prepared, renameFile);
}
+137 -152
View File
@@ -1,182 +1,167 @@
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,
AUDIT_SCRIPT,
AUDIT_WRAPPER,
GUARD_SCRIPT,
GUARD_WRAPPER,
buildWrapper,
createAugmentDocument,
parseAugmentDocument,
type AugmentDocument,
type JsonObject,
type RenderedAugmentDocument,
type RuntimeContract,
isObject,
readHooks,
} from './augment-contract.js';
import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
import {
commitManagedTransaction,
prepareManagedFileChange,
} from './managed-transaction.js';
import { parseStrictJsonObject, type JsonObject } from './strict-json.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;
}
const MAX_SECRET_BYTES = 64 * 1024;
const MAX_CONFIG_BYTES = 512 * 1024;
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) };
await inspectPhysicalDirectory(path.dirname(configPath), 'Auggie configuration directory');
const snapshot = await readPhysicalFile(configPath, 'Auggie user settings', MAX_CONFIG_BYTES);
return snapshot
? parseAugmentDocument(configPath, snapshot.contents)
: createAugmentDocument(configPath);
}
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}`);
export async function writeAugmentDocument(rendered: RenderedAugmentDocument): Promise<void> {
if (!rendered.changed) return;
const change = await prepareManagedFileChange({
filePath: rendered.document.configPath,
label: 'Auggie user settings',
next: rendered.next,
mode: 0o600,
maximumBytes: MAX_CONFIG_BYTES,
expectedSource: rendered.document.raw,
verifyExpectedSource: true,
});
if (!change) return;
await commitManagedTransaction({
displayName: 'Augment Code CLI',
operation: 'uninstall',
directories: [{
path: path.dirname(rendered.document.configPath),
label: 'Auggie configuration directory',
}],
changes: [change],
});
}
function sameAgentId(left: string, right: string): boolean {
return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
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 }>;
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 requireNonEmptyString(value: unknown, field: string, configPath: string): string {
if (typeof value !== 'string' || value.trim().length === 0) {
throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
}
return value;
}
function validateRuntimeConfig(
config: JsonObject,
contract: RuntimeContract,
configPath: string,
): void {
const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
const extra = Object.keys(config).find((key) => !supported.has(key));
if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
requireNonEmptyString(config.org_id, 'org_id', configPath);
requireNonEmptyString(config.kid, 'kid', configPath);
const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
if (!sameAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
throw new Error(`Elydora runtime identity does not match Auggie hooks: ${configPath}`);
}
if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
let baseUrl: URL;
try {
entries = await fsp.readdir(root, { withFileTypes: true });
baseUrl = new URL(rawBaseUrl);
} catch (error) {
if (hasErrorCode(error, 'ENOENT')) return false;
throw new Error(`Read Elydora runtime directory at ${root}: ${errorMessage(error)}`, {
cause: asError(error),
throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
cause: error instanceof Error ? error : new Error(String(error)),
});
}
if (!['http:', 'https:'].includes(baseUrl.protocol)
|| !baseUrl.hostname
|| baseUrl.username
|| baseUrl.password
|| baseUrl.search
|| baseUrl.hash) {
throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
}
}
function validatePrivateKey(contents: string, keyPath: string): void {
const bytes = Buffer.from(contents, 'base64url');
if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
throw new Error(`Elydora private key is invalid: ${keyPath}`);
}
}
function validContractPaths(contract: RuntimeContract, agentDirectory: string): boolean {
return samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))
&& samePath(contract.guardPath, path.join(agentDirectory, GUARD_SCRIPT))
&& samePath(contract.auditPath, path.join(agentDirectory, AUDIT_SCRIPT))
&& samePath(contract.guardWrapperPath, path.join(agentDirectory, GUARD_WRAPPER))
&& samePath(contract.auditWrapperPath, path.join(agentDirectory, AUDIT_WRAPPER));
}
async function runtimeContractExists(contract: RuntimeContract): Promise<boolean> {
const runtimeRoot = path.join(os.homedir(), '.elydora');
const agentDirectory = path.dirname(contract.guardPath);
if (!validContractPaths(contract, agentDirectory)) return false;
if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) {
return false;
}
const configPath = path.join(agentDirectory, 'config.json');
const keyPath = path.join(agentDirectory, 'private.key');
const [config, key, guard, audit, guardWrapper, auditWrapper] = await Promise.all([
readPhysicalFile(configPath, 'Elydora runtime config', MAX_CONFIG_BYTES),
readPhysicalFile(keyPath, 'Elydora private key', MAX_SECRET_BYTES),
readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
readPhysicalFile(contract.guardWrapperPath, 'Auggie guard wrapper'),
readPhysicalFile(contract.auditWrapperPath, 'Auggie audit wrapper'),
]);
if (!config || !key || !guard || !audit || !guardWrapper || !auditWrapper) return false;
const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
validateRuntimeConfig(parsed, contract, configPath);
validatePrivateKey(key.contents, keyPath);
return guard.contents.length > 0
&& audit.contents.length > 0
&& guardWrapper.contents === buildWrapper(contract.guardPath)
&& auditWrapper.contents === buildWrapper(contract.auditPath);
}
export async function augmentRuntimeFilesExist(
contracts: readonly RuntimeContract[],
): Promise<boolean> {
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;
if (await runtimeContractExists(contract)) return true;
}
return false;
}
+25 -21
View File
@@ -3,32 +3,36 @@ import { SUPPORTED_AGENTS } from './registry.js';
import {
AGENT_KEY,
buildHandler,
buildWrapper,
removeManagedHooks,
renderAugmentDocument,
runtimeContracts,
wrapperPaths,
} from './augment-contract.js';
import {
commitAugmentInstallation,
preflightAugmentInstallation,
prepareAugmentInstallation,
} from './augment-installation.js';
import {
augmentRuntimeFilesExist,
readConfig,
removeConfig,
requireRuntime,
runtimeFilesExist,
writeConfig,
writeWrapper,
writeAugmentDocument,
} 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');
managesRuntime: true,
const wrappers = wrapperPaths(config.agentId);
await writeWrapper(wrappers.guardPath, buildWrapper(config.guardScriptPath));
await writeWrapper(wrappers.auditPath, buildWrapper(config.hookScriptPath));
async preflightInstall(config: InstallConfig): Promise<void> {
const document = await readConfig();
await preflightAugmentInstallation(config, document.configPath);
},
async install(config: InstallConfig): Promise<void> {
const document = await readConfig();
const paths = await preflightAugmentInstallation(config, document.configPath);
const wrappers = wrapperPaths(paths.agentDirectory);
const cleaned = removeManagedHooks(document.hooks).hooks;
const hooks = {
@@ -42,7 +46,9 @@ export const augmentPlugin: AgentPlugin = {
{ matcher: '.*', hooks: [buildHandler(wrappers.auditPath)] },
],
};
await writeConfig(document.configPath, { ...document.root, hooks });
const rendered = renderAugmentDocument(document, hooks);
const prepared = await prepareAugmentInstallation(config, rendered);
await commitAugmentInstallation(prepared);
console.log(' Auggie: user-level PreToolUse and PostToolUse hooks installed.');
},
@@ -51,18 +57,16 @@ export const augmentPlugin: AgentPlugin = {
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);
await writeAugmentDocument(renderAugmentDocument(document, result.hooks));
},
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;
const hookScriptExists = hookConfigured
? await augmentRuntimeFilesExist(contracts)
: false;
return {
installed: hookConfigured && hookScriptExists,
agentName: AGENT_KEY,
+27
View File
@@ -38,10 +38,19 @@ export interface ManagedHookSource extends ManagedHookLocation {
readonly source: string;
}
export interface ManagedRuntimeFile {
readonly fileName: string;
readonly label: string;
readonly source: string;
readonly mode: number;
readonly maximumBytes?: number;
}
export interface ManagedInstallationSpec {
readonly agentKey: string;
readonly displayName: string;
readonly hookSources: readonly ManagedHookSource[];
readonly runtimeFiles?: readonly ManagedRuntimeFile[];
readonly config: InstallConfig;
readonly guardOptions?: GuardScriptOptions;
readonly auditOptions?: HookScriptOptions;
@@ -202,6 +211,17 @@ function hookDirectories(sources: readonly ManagedHookSource[]): ManagedDirector
}));
}
function runtimeFilePath(paths: ManagedRuntimePaths, fileName: string): string {
if (!fileName
|| fileName === '.'
|| fileName === '..'
|| fileName.includes('/')
|| fileName.includes('\\')) {
throw new Error(`Managed runtime fileName must be a basename: ${fileName}`);
}
return path.join(paths.agentDirectory, fileName);
}
export async function prepareManagedInstallation(
spec: ManagedInstallationSpec,
guardScript: string,
@@ -240,6 +260,13 @@ export async function prepareManagedInstallation(
next: generateHookScript(spec.agentKey, spec.config.agentId, spec.auditOptions),
mode: 0o700,
}),
...(spec.runtimeFiles ?? []).map((runtimeFile) => prepareManagedFileChange({
filePath: runtimeFilePath(paths, runtimeFile.fileName),
label: runtimeFile.label,
next: runtimeFile.source,
mode: runtimeFile.mode,
maximumBytes: runtimeFile.maximumBytes,
})),
...spec.hookSources.map((source) => prepareManagedFileChange({
filePath: source.filePath,
label: source.label,