@cleocode/adapters 2026.5.37 → 2026.5.40

package/src/providers/pi/install.ts

@@ -2,8 +2,7 @@
  * Pi Install Provider
  *
  * Handles CLEO installation into Pi coding agent environments:
- * - Ensures AGENTS.md has CLEO @-references (project and global scope)
- * - Manages Pi settings.json to register CLEO extension path
+ * - Ensures AGENTS.md has CLEO @-references via CAAMP (project and global scope)
  *
  * Pi uses AGENTS.md (not CLAUDE.md) as its instruction file. The global
  * instruction file lives at `~/.pi/agent/AGENTS.md`; the project-level
@@ -13,42 +12,20 @@
  * environment variables, or by presence of `~/.pi/agent/` directory.
  *
  * @task T553
+ * @task T9019
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 /**
- * Lines that should appear in AGENTS.md to reference CLEO.
- * The CLEO-INJECTION.md path is resolved dynamically to support non-default
- * XDG / OS installation locations (T916).
+ * CLEO @-references injected into Pi instruction files.
+ * Resolved dynamically to support non-default XDG / OS installation locations (T916).
  */
-const INSTRUCTION_REFERENCES = [
-  `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
-  '@.cleo/memory-bridge.md',
-];
-
-/**
- * Resolve the Pi global state root directory.
- *
- * Honours `PI_CODING_AGENT_DIR` env var when set (with `~` expansion),
- * then `PI_HOME`, then falls back to `~/.pi/agent`.
- */
-function getPiAgentDir(): string {
-  const env = process.env['PI_CODING_AGENT_DIR'];
-  if (env !== undefined && env.length > 0) {
-    if (env === '~') return homedir();
-    if (env.startsWith('~/')) return join(homedir(), env.slice(2));
-    return env;
-  }
-  const piHome = process.env['PI_HOME'];
-  if (piHome !== undefined && piHome.length > 0) {
-    return join(piHome, 'agent');
-  }
-  return join(homedir(), '.pi', 'agent');
+function getCleoReferences(): string[] {
+  return [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'];
 }
 
 /**
@@ -56,7 +33,8 @@ function getPiAgentDir(): string {
  *
  * Manages CLEO's integration with Pi by:
  * 1. Ensuring project AGENTS.md contains @-references to CLEO instruction files
- * 2. Ensuring global AGENTS.md (~/.pi/agent/AGENTS.md) contains @-references
+ *    (delegated to CAAMP's canonical {@link ensureProviderInstructionFile}).
+ * 2. Ensuring global AGENTS.md (~/.pi/agent/AGENTS.md) contains @-references.
  *
  * @remarks
  * Installation is idempotent — running install multiple times on the same
@@ -76,22 +54,31 @@ export class PiInstallProvider implements AdapterInstallProvider {
     const installedAt = new Date().toISOString();
     const details: Record<string, unknown> = {};
 
-    // Step 1: Ensure project AGENTS.md has @-references
-    const projectUpdated = this.updateInstructionFile(projectDir, 'AGENTS.md');
+    // Step 1: Ensure project AGENTS.md has @-references via CAAMP canonical API.
+    const projectResult = await ensureProviderInstructionFile('pi', projectDir, {
+      scope: 'project',
+      references: getCleoReferences(),
+    });
+
+    const projectUpdated = projectResult.action !== 'intact';
     if (projectUpdated) {
-      details.instructionFile = join(projectDir, 'AGENTS.md');
+      details.instructionFile = join(projectDir, projectResult.instructFile);
     }
 
-    // Step 2: Ensure global AGENTS.md has @-references (best-effort)
+    // Step 2: Ensure global AGENTS.md has @-references (best-effort).
+    // CAAMP resolves pathGlobal from the registry ($HOME/.pi/agent).
     let globalUpdated = false;
     try {
-      const globalDir = getPiAgentDir();
-      globalUpdated = this.updateInstructionFile(globalDir, 'AGENTS.md');
+      const globalResult = await ensureProviderInstructionFile('pi', projectDir, {
+        scope: 'global',
+        references: getCleoReferences(),
+      });
+      globalUpdated = globalResult.action !== 'intact';
       if (globalUpdated) {
-        details.globalInstructionFile = join(globalDir, 'AGENTS.md');
+        details.globalInstructionFile = globalResult.filePath;
       }
     } catch {
-      // Global install is best-effort — never block project install
+      // Global install is best-effort — never block project install.
     }
 
     const instructionFileUpdated = projectUpdated || globalUpdated;
@@ -114,30 +101,27 @@ export class PiInstallProvider implements AdapterInstallProvider {
   /**
    * Check whether CLEO is installed in the current environment.
    *
-   * Checks for CLEO references in the project AGENTS.md.
+   * Delegates to CAAMP's instruction-file check for project and global scopes.
    */
   async isInstalled(): Promise<boolean> {
-    const agentsMdPath = join(process.cwd(), 'AGENTS.md');
-    if (existsSync(agentsMdPath)) {
-      try {
-        const content = readFileSync(agentsMdPath, 'utf-8');
-        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
-          return true;
-        }
-      } catch {
-        // Fall through
-      }
+    // Check project-level AGENTS.md.
+    try {
+      const result = await ensureProviderInstructionFile('pi', process.cwd(), {
+        scope: 'project',
+        references: getCleoReferences(),
+      });
+      if (result.action === 'intact') return true;
+    } catch {
+      // Fall through
     }
 
-    // Also check global AGENTS.md
+    // Also check global AGENTS.md.
     try {
-      const globalPath = join(getPiAgentDir(), 'AGENTS.md');
-      if (existsSync(globalPath)) {
-        const content = readFileSync(globalPath, 'utf-8');
-        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
-          return true;
-        }
-      }
+      const result = await ensureProviderInstructionFile('pi', process.cwd(), {
+        scope: 'global',
+        references: getCleoReferences(),
+      });
+      if (result.action === 'intact') return true;
     } catch {
       // Fall through
     }
@@ -148,50 +132,14 @@ export class PiInstallProvider implements AdapterInstallProvider {
   /**
    * Ensure AGENTS.md contains @-references to CLEO instruction files.
    *
-   * Creates AGENTS.md if it does not exist. Appends any missing references.
+   * Delegates to CAAMP's canonical {@link ensureProviderInstructionFile}.
    *
    * @param projectDir - Project root directory
    */
   async ensureInstructionReferences(projectDir: string): Promise<void> {
-    this.updateInstructionFile(projectDir, 'AGENTS.md');
-  }
-
-  /**
-   * Update an instruction file with CLEO @-references.
-   *
-   * @param dir - Directory containing the instruction file
-   * @param filename - Name of the instruction file (e.g. "AGENTS.md")
-   * @returns true if the file was created or modified
-   */
-  private updateInstructionFile(dir: string, filename: string): boolean {
-    const filePath = join(dir, filename);
-    let content = '';
-    let existed = false;
-
-    if (existsSync(filePath)) {
-      content = readFileSync(filePath, 'utf-8');
-      existed = true;
-    }
-
-    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
-
-    if (missingRefs.length === 0) {
-      return false;
-    }
-
-    const refsBlock = missingRefs.join('\n');
-
-    if (existed) {
-      // Append missing references
-      const separator = content.endsWith('\n') ? '' : '\n';
-      content = content + separator + refsBlock + '\n';
-    } else {
-      // Create new file with references — ensure parent dir exists
-      mkdirSync(dir, { recursive: true });
-      content = refsBlock + '\n';
-    }
-
-    writeFileSync(filePath, content, 'utf-8');
-    return true;
+    await ensureProviderInstructionFile('pi', projectDir, {
+      scope: 'project',
+      references: getCleoReferences(),
+    });
   }
 }