@cleocode/adapters 2026.10.4 → 2026.10.5-rc.ci.672

package/src/providers/kimi/install.ts

@@ -14,6 +14,7 @@ import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * Install provider for Kimi.
@@ -58,15 +59,16 @@ export class KimiInstallProvider implements AdapterInstallProvider {
     const installedAt = new Date().toISOString();
     const details: Record<string, unknown> = {};
 
-    const result = await ensureProviderInstructionFile('kimi', projectDir, {
+    const result = await ensureProjectInstructionFile('kimi', projectDir, {
       references: [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'],
       scope: 'project',
     });
 
-    const instructionFileUpdated = result.action !== 'intact';
+    const instructionFileUpdated = result !== null && result.action !== 'intact';
     if (instructionFileUpdated) {
       details.instructionFile = result.filePath;
     }
+    if (result === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     return {
       success: true,

package/src/providers/openai-sdk/install.ts

@@ -14,6 +14,7 @@ import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * Install provider for the OpenAI SDK adapter (Vercel AI SDK).
@@ -40,15 +41,17 @@ export class OpenAiSdkInstallProvider implements AdapterInstallProvider {
     const details: Record<string, unknown> = {};
 
     // Step 1: Ensure AGENTS.md has @-references via CAAMP registry
-    const instructionResult = await ensureProviderInstructionFile('openai-sdk', projectDir, {
+    const instructionResult = await ensureProjectInstructionFile('openai-sdk', projectDir, {
       references: [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'],
       scope: 'project',
     });
 
-    const instructionFileUpdated = instructionResult.action !== 'intact';
+    const instructionFileUpdated =
+      instructionResult !== null && instructionResult.action !== 'intact';
     if (instructionFileUpdated) {
       details.instructionFile = instructionResult.filePath;
     }
+    if (instructionResult === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     // Step 2: Create .openai config directory stub
     const configCreated = this.ensureConfigDir(projectDir);

package/src/providers/opencode/install.ts

@@ -25,6 +25,7 @@ import {
   installProviderHookTemplates,
 } from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * Install provider for OpenCode.
@@ -57,15 +58,16 @@ export class OpenCodeInstallProvider implements AdapterInstallProvider {
     const details: Record<string, unknown> = {};
 
     // Step 1: Ensure AGENTS.md has @-references via CAAMP canonical API.
-    const instructResult = await ensureProviderInstructionFile('opencode', projectDir, {
+    const instructResult = await ensureProjectInstructionFile('opencode', projectDir, {
       scope: 'project',
       references: [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'],
     });
 
-    const instructionFileUpdated = instructResult.action !== 'intact';
+    const instructionFileUpdated = instructResult !== null && instructResult.action !== 'intact';
     if (instructionFileUpdated) {
       details.instructionFile = join(projectDir, instructResult.instructFile);
     }
+    if (instructResult === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     // Step 2 (T1013): Install PreCompact hook templates + generate the JS
     // plugin wrapper that spawns the bash shim on

package/src/providers/pi/install.ts

@@ -19,6 +19,7 @@ import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * CLEO @-references injected into Pi instruction files.
@@ -55,15 +56,16 @@ export class PiInstallProvider implements AdapterInstallProvider {
     const details: Record<string, unknown> = {};
 
     // Step 1: Ensure project AGENTS.md has @-references via CAAMP canonical API.
-    const projectResult = await ensureProviderInstructionFile('pi', projectDir, {
+    const projectResult = await ensureProjectInstructionFile('pi', projectDir, {
       scope: 'project',
       references: getCleoReferences(),
     });
 
-    const projectUpdated = projectResult.action !== 'intact';
+    const projectUpdated = projectResult !== null && projectResult.action !== 'intact';
     if (projectUpdated) {
       details.instructionFile = join(projectDir, projectResult.instructFile);
     }
+    if (projectResult === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     // Step 2: Ensure global AGENTS.md has @-references (best-effort).
     // CAAMP resolves pathGlobal from the registry ($HOME/.pi/agent).

package/src/providers/shared/__tests__/heavy-command-hook-install.test.ts

@@ -43,6 +43,7 @@ import { pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ClaudeCodeInstallProvider } from '../../claude-code/install.js';
 import { CodexInstallProvider } from '../../codex/install.js';
+import { CursorInstallProvider } from '../../cursor/install.js';
 import { OpenCodeInstallProvider } from '../../opencode/install.js';
 import {
   clearOlderCleoMarkers,
@@ -591,6 +592,25 @@ describe('installer wiring', () => {
       false,
     );
     expect(isUserHomeDir(join(home, 'project'))).toBe(false);
+    // T13227: no instruction file at $HOME either; providers load ~/CLAUDE.md
+    // and ~/AGENTS.md into every session under it.
+    expect(results.map((r) => r.details?.instructionFile)).toEqual([
+      'skipped',
+      'skipped',
+      'skipped',
+    ]);
+    expect(existsSync(join(home, 'CLAUDE.md'))).toBe(false);
+    expect(existsSync(join(home, 'AGENTS.md'))).toBe(false);
+  });
+
+  it("T13257: Cursor at $HOME skips its hooks (~/.cursor/hooks.json is Cursor's user-global hooks) and rule files", async () => {
+    const home = process.env.HOME as string;
+    const r = await new CursorInstallProvider().install({ projectDir: home });
+    expect(r.details?.hookTemplates).toBe('skipped');
+    expect(r.details?.instructionFiles).toBe('skipped');
+    expect(existsSync(join(home, '.cursor', 'hooks.json'))).toBe(false);
+    expect(existsSync(join(home, '.cursor', 'hooks'))).toBe(false);
+    expect(existsSync(join(home, '.cursorrules'))).toBe(false);
   });
 
   it('Codex and opencode install only when a mode is passed', async () => {

package/src/providers/shared/heavy-command-hook-install.ts

@@ -101,9 +101,14 @@ export const HEAVY_TOOL_WORDS: readonly string[] = Object.freeze([
  */
 export type HeavyHookSyncResult = 'installed' | 'updated' | 'removed' | 'unchanged' | 'skipped';
 
+/**
+ * `path` through the native realpath, which returns the case stored on disk,
+ * so a differently cased spelling of the home directory on a case-insensitive
+ * volume still matches it (T13227 review).
+ */
 function canonical(path: string): string {
   try {
-    return realpathSync(path);
+    return realpathSync.native(path);
   } catch {
     return resolve(path);
   }

package/src/providers/shared/project-instruction-file.ts

@@ -0,0 +1,47 @@
+/**
+ * A provider's PROJECT instruction file, skipped (not failed) at a project
+ * rooted at the home directory (T13227).
+ *
+ * Providers load CLAUDE.md / AGENTS.md / GEMINI.md from the working directory
+ * up through every ancestor, so a file at `$HOME` reaches every session under
+ * it: CAAMP refuses it with `HomeInstructionFileError`. An adapter's install
+ * reports that step as `skipped` and carries on with the rest, the way the
+ * heavy-command hook already skips the home directory (T12983).
+ *
+ * @task T13227
+ */
+
+import {
+  type EnsureProviderInstructionFileOptions,
+  type EnsureProviderInstructionFileResult,
+  ensureProviderInstructionFile,
+  HomeInstructionFileError,
+} from '@cleocode/caamp';
+
+/**
+ * Ensure a provider's project instruction file, or `null` when the project is
+ * the home directory and the file was refused (nothing written).
+ *
+ * @param providerId - CAAMP provider id.
+ * @param projectDir - the project root.
+ * @param options - references, content, scope.
+ * @returns the CAAMP result, or `null` when skipped at `$HOME`.
+ *
+ * @example
+ * ```typescript
+ * const r = await ensureProjectInstructionFile('codex', projectDir, { scope: 'project' });
+ * if (r === null) details.instructionFile = 'skipped';
+ * ```
+ */
+export async function ensureProjectInstructionFile(
+  providerId: string,
+  projectDir: string,
+  options: EnsureProviderInstructionFileOptions,
+): Promise<EnsureProviderInstructionFileResult | null> {
+  try {
+    return await ensureProviderInstructionFile(providerId, projectDir, options);
+  } catch (err) {
+    if (err instanceof HomeInstructionFileError) return null;
+    throw err;
+  }
+}