@cleocode/adapters 2026.9.18 → 2026.9.20

package/src/providers/claude-code/install.ts

@@ -10,23 +10,23 @@
  * @task T5240
  */
 
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ensureProviderInstructionFile } from '@cleocode/caamp';
+import { ensureProviderInstructionFile, updateJsonConfigFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import {
   type InstallHookTemplatesResult,
   installProviderHookTemplates,
 } from '../shared/hook-template-installer.js';
+import {
+  appendHookEntry,
+  claudeSettingsPath,
+  hasCleoHook,
+  hookMap,
+  isPlainObject,
+} from './paths.js';
 
 /** Resolve Claude Code's config directory, honoring the documented CI override. */
 function getClaudeConfigDir(): string {
@@ -80,21 +80,37 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       details.commands = commandsInstalled;
     }
 
+    // T12385: settings.json writes are locked + atomic, and a malformed file
+    // aborts the write and is reported here — it is never reset to `{}`.
+    const settingsErrors: string[] = [];
+
     // Step 3: Register plugin in ~/.claude/settings.json
-    const pluginResult = this.registerPlugin();
-    if (pluginResult) {
-      details.plugin = pluginResult;
+    try {
+      const pluginResult = await this.registerPlugin();
+      if (pluginResult) {
+        details.plugin = pluginResult;
+      }
+    } catch (err) {
+      settingsErrors.push(err instanceof Error ? err.message : String(err));
     }
 
     // Step 4 (T1013): Install PreCompact hook templates + wire the handler
     // command into ~/.claude/settings.json's `PreCompact` event.
-    const hookResult = this.installHookTemplates();
-    if (hookResult) {
-      details.hookTemplates = hookResult;
+    try {
+      const hookResult = await this.installHookTemplates();
+      if (hookResult) {
+        details.hookTemplates = hookResult;
+      }
+    } catch (err) {
+      settingsErrors.push(err instanceof Error ? err.message : String(err));
+    }
+
+    if (settingsErrors.length > 0) {
+      details.settingsErrors = settingsErrors;
     }
 
     return {
-      success: true,
+      success: settingsErrors.length === 0,
       installedAt,
       instructionFileUpdated,
       details,
@@ -115,7 +131,7 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    */
   async isInstalled(): Promise<boolean> {
     // Check ~/.claude/settings.json for plugin registration
-    const settingsPath = join(getClaudeConfigDir(), 'settings.json');
+    const settingsPath = claudeSettingsPath();
     if (existsSync(settingsPath)) {
       try {
         const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
@@ -179,38 +195,28 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    *
    * @returns Description of what was registered, or null if no change needed
    */
-  private registerPlugin(): string | null {
-    const claudeDir = getClaudeConfigDir();
-    const settingsPath = join(claudeDir, 'settings.json');
-
-    let settings: Record<string, unknown> = {};
-    if (existsSync(settingsPath)) {
-      try {
-        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-      } catch {
-        // Start fresh
-      }
-    }
-
-    const enabledPlugins = (settings.enabledPlugins as Record<string, boolean>) ?? {};
+  private async registerPlugin(): Promise<string | null> {
     const pluginKey = 'cleo@cleocode';
+    const wrote = await updateJsonConfigFile(claudeSettingsPath(), (settings) => {
+      const enabledPlugins = settings.enabledPlugins ?? {};
+      if (!isPlainObject(enabledPlugins)) {
+        throw new Error('settings.json "enabledPlugins" is not an object; not modifying it');
+      }
+      if (enabledPlugins[pluginKey] === true) {
+        return false;
+      }
 
-    if (enabledPlugins[pluginKey] === true) {
-      return null;
-    }
-
-    // Disable old claude-mem if present
-    if (enabledPlugins['claude-mem@thedotmack'] === true) {
-      enabledPlugins['claude-mem@thedotmack'] = false;
-    }
-
-    enabledPlugins[pluginKey] = true;
-    settings.enabledPlugins = enabledPlugins;
+      // Disable old claude-mem if present
+      if (enabledPlugins['claude-mem@thedotmack'] === true) {
+        enabledPlugins['claude-mem@thedotmack'] = false;
+      }
 
-    mkdirSync(claudeDir, { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+      enabledPlugins[pluginKey] = true;
+      settings.enabledPlugins = enabledPlugins;
+      return true;
+    });
 
-    return `Enabled ${pluginKey} in ~/.claude/settings.json`;
+    return wrote ? `Enabled ${pluginKey} in ~/.claude/settings.json` : null;
   }
 
   /**
@@ -233,10 +239,10 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    *
    * @task T1013
    */
-  private installHookTemplates(): {
+  private async installHookTemplates(): Promise<{
     templates: InstallHookTemplatesResult;
     settingsEntryAdded: boolean;
-  } | null {
+  } | null> {
     const claudeDir = getClaudeConfigDir();
     const hooksDir = join(claudeDir, 'hooks');
 
@@ -254,7 +260,7 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
     }
 
     // 2. Wire the PreCompact event in ~/.claude/settings.json.
-    const settingsEntryAdded = this.registerPreCompactHook(
+    const settingsEntryAdded = await this.registerPreCompactHook(
       join(hooksDir, 'precompact-safestop.sh'),
     );
 
@@ -279,55 +285,23 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    *
    * @task T1013
    */
-  private registerPreCompactHook(shimPath: string): boolean {
-    const claudeDir = getClaudeConfigDir();
-    const settingsPath = join(claudeDir, 'settings.json');
-
-    let settings: Record<string, unknown> = {};
-    if (existsSync(settingsPath)) {
-      try {
-        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-      } catch {
-        // Start fresh on corrupt settings — safer than aborting install.
+  private async registerPreCompactHook(shimPath: string): Promise<boolean> {
+    return updateJsonConfigFile(claudeSettingsPath(), (settings) => {
+      const hooks = hookMap(settings);
+      if (hasCleoHook(hooks.PreCompact, 'precompact-safestop.sh')) {
+        return false;
       }
-    }
-
-    const hooks = (settings.hooks as Record<string, unknown[]> | undefined) ?? {};
-    const preCompactEntries = (hooks.PreCompact as unknown[] | undefined) ?? [];
-
-    const alreadyWired = preCompactEntries.some(
-      (entry) =>
-        typeof entry === 'object' &&
-        entry !== null &&
-        Array.isArray((entry as Record<string, unknown>).hooks) &&
-        ((entry as Record<string, unknown>).hooks as Array<Record<string, unknown>>).some(
-          (h) =>
-            typeof h.command === 'string' &&
-            (h.command as string).includes('# cleo-hook') &&
-            (h.command as string).includes('precompact-safestop.sh'),
-        ),
-    );
-
-    if (alreadyWired) {
-      return false;
-    }
-
-    preCompactEntries.push({
-      matcher: '',
-      hooks: [
-        {
-          type: 'command',
-          command: `"${shimPath}" # cleo-hook`,
-          timeout: 30,
-        },
-      ],
+      appendHookEntry(hooks, 'PreCompact', {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `"${shimPath}" # cleo-hook`,
+            timeout: 30,
+          },
+        ],
+      });
+      return true;
     });
-
-    hooks.PreCompact = preCompactEntries;
-    settings.hooks = hooks;
-
-    mkdirSync(claudeDir, { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    return true;
   }
 }

package/src/providers/claude-code/paths.ts

@@ -44,3 +44,158 @@ export class ClaudeCodePathProvider implements AdapterPathProvider {
     return process.env['CLAUDE_MEM_DB'] ?? join(homedir(), '.claude-mem', 'claude-mem.db');
   }
 }
+
+/**
+ * Resolve Claude Code's `settings.json`, honouring `CLAUDE_SETTINGS` and
+ * `CLAUDE_HOME`.
+ *
+ * @remarks
+ * The single resolver for every adapter write to the settings file (T12385).
+ * Hook registration previously hard-coded `~/.claude/settings.json` while the
+ * installer honoured `CLAUDE_HOME`, so the two wrote different files whenever
+ * the override was set.
+ *
+ * @returns Absolute path of the settings file
+ *
+ * @example
+ * ```typescript
+ * const settingsPath = claudeSettingsPath();
+ * ```
+ */
+export function claudeSettingsPath(): string {
+  return (
+    new ClaudeCodePathProvider().getSettingsPath() ?? join(homedir(), '.claude', 'settings.json')
+  );
+}
+
+/** Marker CLEO puts in every hook command it owns. */
+const CLEO_HOOK_MARKER = '# cleo-hook';
+
+/**
+ * Whether a parsed settings value is a plain JSON object.
+ *
+ * @param value - Any parsed JSON value
+ * @returns `true` for a non-null, non-array object
+ *
+ * @example
+ * ```typescript
+ * isPlainObject(settings.enabledPlugins);
+ * ```
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether a settings.json hook entry carries a CLEO-owned command.
+ *
+ * @param entry - One element of a `hooks.<Event>` array
+ * @param commandIncludes - Extra substring the CLEO command must contain
+ * @returns `true` when one of the entry's commands has the `# cleo-hook` marker
+ *
+ * @example
+ * ```typescript
+ * isCleoHookEntry({ hooks: [{ type: "command", command: "x # cleo-hook" }] }); // true
+ * ```
+ */
+export function isCleoHookEntry(entry: unknown, commandIncludes?: string): boolean {
+  if (!isPlainObject(entry) || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some(
+    (hook) =>
+      isPlainObject(hook) &&
+      typeof hook.command === 'string' &&
+      hook.command.includes(CLEO_HOOK_MARKER) &&
+      (commandIncludes === undefined || hook.command.includes(commandIncludes)),
+  );
+}
+
+/**
+ * Whether a `hooks.<Event>` value holds a CLEO-owned entry.
+ *
+ * @param entries - The event's value (non-arrays hold none)
+ * @param commandIncludes - Extra substring the CLEO command must contain
+ * @returns `true` when a CLEO entry is present
+ *
+ * @example
+ * ```typescript
+ * hasCleoHook(hookMap(settings).Stop);
+ * ```
+ */
+export function hasCleoHook(entries: unknown, commandIncludes?: string): boolean {
+  return Array.isArray(entries) && entries.some((e) => isCleoHookEntry(e, commandIncludes));
+}
+
+/**
+ * Return the settings object's `hooks` map, creating an empty one if absent.
+ *
+ * @param settings - Parsed settings.json
+ * @returns The live `hooks` object (mutations apply to `settings`)
+ * @throws Error when `hooks` exists but is not an object — the caller's write
+ *   is aborted and the file left untouched
+ *
+ * @example
+ * ```typescript
+ * const hooks = hookMap(settings);
+ * ```
+ */
+export function hookMap(settings: Record<string, unknown>): Record<string, unknown> {
+  const existing = settings.hooks;
+  if (existing === undefined) {
+    const created: Record<string, unknown> = {};
+    settings.hooks = created;
+    return created;
+  }
+  if (!isPlainObject(existing)) {
+    throw new Error('settings.json "hooks" is not an object; not modifying it');
+  }
+  return existing;
+}
+
+/**
+ * Append a hook entry to `hooks[event]`, preserving existing entries.
+ *
+ * @param hooks - The settings `hooks` map
+ * @param event - Native event name (e.g. `Stop`, `PreCompact`)
+ * @param entry - Entry to append
+ * @throws Error when `hooks[event]` exists but is not an array
+ *
+ * @example
+ * ```typescript
+ * appendHookEntry(hookMap(settings), "Stop", { matcher: "", hooks: [] });
+ * ```
+ */
+export function appendHookEntry(
+  hooks: Record<string, unknown>,
+  event: string,
+  entry: Record<string, unknown>,
+): void {
+  const existing = hooks[event];
+  if (existing !== undefined && !Array.isArray(existing)) {
+    throw new Error(`settings.json "hooks.${event}" is not an array; not modifying it`);
+  }
+  hooks[event] = [...(existing ?? []), entry];
+}
+
+/**
+ * Remove every CLEO-owned entry from every event array in `hooks`.
+ *
+ * @param hooks - The settings `hooks` map
+ * @returns Whether anything was removed
+ *
+ * @example
+ * ```typescript
+ * const changed = removeCleoHookEntries(hookMap(settings));
+ * ```
+ */
+export function removeCleoHookEntries(hooks: Record<string, unknown>): boolean {
+  let changed = false;
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const kept = entries.filter((e) => !isCleoHookEntry(e));
+    if (kept.length !== entries.length) {
+      hooks[event] = kept;
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/providers/cursor/__tests__/adapter.test.ts

@@ -45,6 +45,13 @@ vi.mock('@cleocode/caamp', () => ({
     action: 'added',
     providerId: 'cursor',
   }),
+  // T12385: Cursor's rule files and hooks.json go through the CAAMP writers.
+  ensureProviderRuleFile: vi.fn().mockResolvedValue({
+    filePath: '/tmp/test-project/.cursor/rules/cleo.mdc',
+    action: 'created',
+    providerId: 'cursor',
+  }),
+  updateJsonConfigFile: vi.fn().mockResolvedValue(true),
 }));
 
 describe('CursorAdapter', () => {

package/src/providers/cursor/__tests__/hooks-install.test.ts

@@ -95,4 +95,40 @@ describe('CursorInstallProvider — PreCompact hook templates', () => {
     };
     expect((config.hooks?.preCompact ?? []).length).toBe(1);
   });
+
+  it('T12385: reports a malformed hooks.json and leaves it byte-identical', async () => {
+    const hooksJsonPath = join(projectDir, '.cursor', 'hooks.json');
+    mkdirSync(join(projectDir, '.cursor'), { recursive: true });
+    const malformed = '{ "hooks": { "preCompact": [ ';
+    writeFileSync(hooksJsonPath, malformed, 'utf-8');
+
+    const result = await new CursorInstallProvider().install({ projectDir });
+
+    expect(readFileSync(hooksJsonPath, 'utf-8')).toBe(malformed);
+    expect(result.success).toBe(false);
+    expect(String(result.details?.hooksError)).toMatch(/not a valid JSON object/);
+  });
+
+  it('T12385: writes rule files through the CAAMP writer (managed block, registry references)', async () => {
+    const legacyPath = join(projectDir, '.cursorrules');
+    // A pre-CAAMP .cursorrules with the old bare reference lines appended.
+    writeFileSync(
+      legacyPath,
+      '# Project Rules\nUse TypeScript.\n@~/.cleo/templates/CLEO-INJECTION.md\n@.cleo/memory-bridge.md\n',
+      'utf-8',
+    );
+
+    await new CursorInstallProvider().install({ projectDir });
+
+    const legacy = readFileSync(legacyPath, 'utf-8');
+    expect(legacy).toContain('# Project Rules\nUse TypeScript.');
+    expect(legacy).toContain('<!-- CAAMP:START -->');
+    expect(legacy.match(/CLEO-INJECTION\.md/g)).toHaveLength(1);
+
+    const mdc = readFileSync(join(projectDir, '.cursor', 'rules', 'cleo.mdc'), 'utf-8');
+    expect(mdc.startsWith('---\n')).toBe(true);
+    expect(mdc).toContain('alwaysApply: true');
+    expect(mdc).toContain('<!-- CAAMP:START -->');
+    expect(mdc).toContain('@.cleo/memory-bridge.md');
+  });
 });