@cleocode/adapters 2026.4.101 → 2026.4.102

package/dist/providers/claude-code/install.d.ts

@@ -74,5 +74,41 @@ export declare class ClaudeCodeInstallProvider implements AdapterInstallProvider
      * @returns Description of what was registered, or null if no change needed
      */
     private registerPlugin;
+    /**
+     * Install the CLEO PreCompact hook templates for Claude Code (T1013).
+     *
+     * Writes two files to `~/.claude/hooks/`:
+     * 1. `cleo-precompact-core.sh` — universal CLEO safestop helper (shared
+     *    across all providers; sourced by the provider-specific shim).
+     * 2. `precompact-safestop.sh` — Claude-Code-flavoured wrapper that invokes
+     *    `cleo memory precompact-flush` and `cleo safestop`.
+     *
+     * Also registers a `PreCompact` entry in `~/.claude/settings.json` so Claude
+     * Code runs the hook when auto-compact fires (at 95% context).
+     *
+     * Idempotent: subsequent installs skip unchanged files and do not duplicate
+     * the settings.json hook entry.
+     *
+     * @returns Install summary (paths written + config change description), or
+     *   `null` when no change was required.
+     *
+     * @task T1013
+     */
+    private installHookTemplates;
+    /**
+     * Register the PreCompact hook command in `~/.claude/settings.json`.
+     *
+     * The Claude Code native event name for the canonical `PreCompact` event is
+     * `PreCompact` (identity mapping — see `hook-mappings.json`). The entry is
+     * tagged with `# cleo-hook` so the uninstall flow can identify and remove
+     * our additions without touching user-authored hooks.
+     *
+     * @param shimPath - Absolute path to the installed `precompact-safestop.sh`.
+     * @returns `true` when a new hook entry was written, `false` when an
+     *   equivalent entry was already present.
+     *
+     * @task T1013
+     */
+    private registerPreCompactHook;
 }
 //# sourceMappingURL=install.d.ts.map

package/dist/providers/claude-code/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAiCvB"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,sBAAsB;CAmD/B"}

package/dist/providers/cursor/install.d.ts

@@ -4,6 +4,7 @@
  * Handles CLEO installation into Cursor environments:
  * - Ensures .cursorrules has CLEO @-references (legacy format)
  * - Creates .cursor/rules/cleo.mdc with CLEO references (modern format)
+ * - Installs PreCompact hook shell shims + wires them into .cursor/hooks.json (T1013)
  *
  * Cursor supports two instruction file formats:
  * 1. Legacy: .cursorrules (flat file, project root)
@@ -12,6 +13,7 @@
  * This provider writes to both for maximum compatibility.
  *
  * @task T5240
+ * @task T1013
  */
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 /**
@@ -20,6 +22,7 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  * Manages CLEO's integration with Cursor by:
  * 1. Creating/updating .cursorrules with @-references (legacy)
  * 2. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ * 3. Installing the PreCompact hook shim + registering it in .cursor/hooks.json (T1013)
  *
  * @remarks
  * Installation is idempotent and writes to both instruction file formats
@@ -83,5 +86,38 @@ export declare class CursorInstallProvider implements AdapterInstallProvider {
      * Get list of instruction files that were updated.
      */
     private getUpdatedFileList;
+    /**
+     * Install the CLEO PreCompact hook templates for Cursor (T1013).
+     *
+     * Writes two files to `<projectDir>/.cursor/hooks/`:
+     * 1. `cleo-precompact-core.sh` — universal CLEO safestop helper.
+     * 2. `precompact.sh` — Cursor-flavoured wrapper.
+     *
+     * Also registers a `preCompact` entry in `.cursor/hooks.json`. The native
+     * event name `preCompact` comes from CAAMP's `hook-mappings.json` SSoT.
+     *
+     * Idempotent: re-running install skips unchanged files and avoids
+     * duplicating the hooks.json entry.
+     *
+     * @param projectDir - Project root directory.
+     * @returns Install summary, or `null` when no change was required.
+     *
+     * @task T1013
+     */
+    private installHookTemplates;
+    /**
+     * Register the PreCompact hook command in `.cursor/hooks.json`.
+     *
+     * Cursor's native event name for the canonical `PreCompact` is `preCompact`
+     * (camelCase — see CAAMP `hook-mappings.json`). Entries are tagged with a
+     * `# cleo-hook` comment so they can be cleanly removed on uninstall.
+     *
+     * @param projectDir - Project root directory.
+     * @param shimPath - Absolute path to the installed `precompact.sh`.
+     * @returns `true` when a new entry was written, `false` when already wired.
+     *
+     * @task T1013
+     */
+    private registerPreCompactHook;
 }
 //# sourceMappingURL=install.d.ts.map

package/dist/providers/cursor/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAajG;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAoB9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAqBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA2B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAqBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;CAyC/B"}

package/dist/providers/opencode/install.d.ts

@@ -3,8 +3,10 @@
  *
  * Handles CLEO installation into OpenCode environments:
  * - Ensures AGENTS.md has CLEO @-references
+ * - Installs PreCompact hook shell shims + a JS plugin wrapper (T1013)
  *
  * @task T5240
+ * @task T1013
  */
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 /**
@@ -12,11 +14,17 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  *
  * Manages CLEO's integration with OpenCode by:
  * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ * 2. Installing PreCompact hook shell templates + generating the JS plugin
+ *    wrapper that spawns the shim on `experimental.session.compacting` (T1013).
  *
  * @remarks
  * Installation is idempotent -- running install multiple times on the same
- * project produces the same result. Only AGENTS.md is managed; OpenCode's
- * plugin system is handled separately by the hook provider.
+ * project produces the same result. OpenCode's plugin system is the native
+ * hook surface (OpenCode has no config-file hook registry like Claude Code or
+ * Cursor), so the installer writes a JS plugin that subscribes to the native
+ * event and spawns the shell shim as a child process. This keeps the DRY
+ * contract: all providers funnel through the shared `cleo-precompact-core.sh`
+ * helper and end up in the `cleo` CLI.
  */
 export declare class OpenCodeInstallProvider implements AdapterInstallProvider {
     /**
@@ -52,5 +60,42 @@ export declare class OpenCodeInstallProvider implements AdapterInstallProvider {
      * @returns true if the file was created or modified
      */
     private updateInstructionFile;
+    /**
+     * Install the CLEO PreCompact hook templates for OpenCode (T1013).
+     *
+     * OpenCode uses a JavaScript plugin system, not config-based hooks. The
+     * installer:
+     *
+     * 1. Writes the shared bash helper and OpenCode-flavoured `precompact.sh`
+     *    to `<projectDir>/.opencode/plugins/hooks/` so the shim can be spawned
+     *    as a child process.
+     * 2. Generates an OpenCode plugin `.opencode/plugins/cleo-precompact.js`
+     *    that subscribes to `experimental.session.compacting` (CAAMP native
+     *    event for the canonical `PreCompact`) and spawns the shim.
+     *
+     * Idempotent.
+     *
+     * @param projectDir - Project root directory.
+     * @returns Install summary, or `null` when no change was required.
+     *
+     * @task T1013
+     */
+    private installHookTemplates;
+    /**
+     * Write an OpenCode JavaScript plugin that spawns `precompact.sh` when the
+     * canonical `PreCompact` event fires. OpenCode exposes the event natively as
+     * `experimental.session.compacting` (see CAAMP `hook-mappings.json`).
+     *
+     * The generated file is idempotent — overwritten only when its content
+     * differs from the target on disk. Uses `child_process.spawn` so the bash
+     * shim runs in a separate process and does not block the compaction path.
+     *
+     * @param pluginsDir - Absolute path to `.opencode/plugins/`.
+     * @param shimPath - Absolute path to the installed `precompact.sh`.
+     * @returns `true` when the plugin file was written, `false` when unchanged.
+     *
+     * @task T1013
+     */
+    private writePrecompactPlugin;
 }
 //# sourceMappingURL=install.d.ts.map

package/dist/providers/opencode/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/opencode/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAajG;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,sBAAsB;IACpE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAoB9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;CA8B9B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/opencode/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiBjG;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,YAAW,sBAAsB;IACpE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA4B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBrC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA+B7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAiC5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;CA0C9B"}

package/dist/providers/shared/hook-template-installer.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared hook-template installer for provider adapters.
+ *
+ * Each provider ships its own PreCompact shell shim under
+ * `packages/adapters/src/providers/<provider>/templates/hooks/` which sources
+ * the universal helper at
+ * `packages/adapters/src/providers/shared/templates/hooks/cleo-precompact-core.sh`.
+ *
+ * This module wires the templates into the provider's hooks directory at
+ * install time. Provider-specific {@link AdapterInstallProvider} implementations
+ * call {@link installProviderHookTemplates} with their own provider id, and the
+ * installer consults CAAMP's `hook-mappings.json` SSoT to verify the provider
+ * supports the required canonical event and handler type before writing.
+ *
+ * DRY invariant: all shims source the same core helper — adapter-specific
+ * shims only add provider-flavoured banners and `$CLEO_PRECOMPACT_*` env
+ * handling.
+ *
+ * @task T1013
+ * @epic T1000
+ */
+/** Identifiers for providers that ship bash hook templates. */
+export type HookTemplateProviderId = 'claude-code' | 'cursor' | 'opencode' | 'gemini-cli';
+/**
+ * Result returned by {@link installProviderHookTemplates}.
+ *
+ * @remarks
+ * Paths are absolute and point at the filesystem locations the installer
+ * actually wrote to. When no template files needed copying (e.g. because the
+ * destination already contained identical files), `installedFiles` is empty
+ * and `skipped` carries the reason-keyed paths instead.
+ */
+export interface InstallHookTemplatesResult {
+    /** Provider identifier the templates were installed for. */
+    provider: HookTemplateProviderId;
+    /** Absolute path to the hooks directory that received the templates. */
+    targetDir: string;
+    /** Absolute paths to files written during this install invocation. */
+    installedFiles: string[];
+    /** Files that were not written (already present and identical). */
+    skipped: string[];
+}
+/**
+ * Options for {@link installProviderHookTemplates}.
+ */
+export interface InstallHookTemplatesOptions {
+    /** Provider to install hook templates for. */
+    provider: HookTemplateProviderId;
+    /** Absolute path to the hooks directory that should receive the shims. */
+    targetDir: string;
+    /**
+     * When `true`, overwrite existing files even if their contents match.
+     *
+     * @defaultValue `false`
+     */
+    force?: boolean;
+}
+/**
+ * Install the CLEO PreCompact hook templates for a provider.
+ *
+ * Writes two files into `targetDir`:
+ *
+ * 1. `cleo-precompact-core.sh` — universal helper (shared across all providers)
+ * 2. `<provider-shim>.sh` — provider-flavoured shim that sources the helper
+ *
+ * The shim invokes only the universal CLEO CLI (`cleo memory precompact-flush`
+ * and `cleo safestop …`) — adapters never reach into core internals.
+ *
+ * @param options - Installation target and provider id.
+ * @returns Paths written, paths skipped, and the resolved target directory.
+ *
+ * @example
+ * ```typescript
+ * import { homedir } from 'node:os';
+ * import { join } from 'node:path';
+ * import { installProviderHookTemplates } from '@cleocode/adapters';
+ *
+ * const result = installProviderHookTemplates({
+ *   provider: 'claude-code',
+ *   targetDir: join(homedir(), '.claude', 'hooks'),
+ * });
+ * // result.installedFiles includes both scripts on first run.
+ * ```
+ *
+ * @task T1013
+ * @public
+ */
+export declare function installProviderHookTemplates(options: InstallHookTemplatesOptions): InstallHookTemplatesResult;
+/**
+ * Resolve the source-side path of a provider's hook template for inspection
+ * and testing. Returns the absolute path where the installer will read from.
+ *
+ * @param provider - Provider identifier.
+ * @returns Absolute path to the provider's shim template file.
+ *
+ * @task T1013
+ * @public
+ */
+export declare function getProviderHookTemplatePath(provider: HookTemplateProviderId): string;
+/**
+ * Resolve the source-side path of the shared universal helper.
+ *
+ * @returns Absolute path to `cleo-precompact-core.sh` in the adapter package.
+ *
+ * @task T1013
+ * @public
+ */
+export declare function getSharedHookCorePath(): string;
+//# sourceMappingURL=hook-template-installer.d.ts.map

package/dist/providers/shared/hook-template-installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-template-installer.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/hook-template-installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAE1F;;;;;;;;GAQG;AACH,MAAM,WAAW,0BAA0B;IACzC,4DAA4D;IAC5D,QAAQ,EAAE,sBAAsB,CAAC;IACjC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,QAAQ,EAAE,sBAAsB,CAAC;IACjC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAqHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAyB5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAEpF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.4.101",
+  "version": "2026.4.102",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -15,8 +15,8 @@
     "@ai-sdk/anthropic": "^3.0.69",
     "@ai-sdk/openai": "^2.0.53",
     "ai": "^6.0.168",
-    "@cleocode/caamp": "2026.4.101",
-    "@cleocode/contracts": "2026.4.101"
+    "@cleocode/caamp": "2026.4.102",
+    "@cleocode/contracts": "2026.4.102"
   },
   "license": "MIT",
   "engines": {
@@ -29,7 +29,7 @@
   "devDependencies": {
     "@types/node": "^22.19.15",
     "vitest": "^4.1.4",
-    "@cleocode/playbooks": "2026.4.101"
+    "@cleocode/playbooks": "2026.4.102"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -84,5 +84,16 @@ export {
   OpenCodeInstallProvider,
   OpenCodeSpawnProvider,
 } from './providers/opencode/index.js';
+export type {
+  HookTemplateProviderId,
+  InstallHookTemplatesOptions,
+  InstallHookTemplatesResult,
+} from './providers/shared/hook-template-installer.js';
+// T1013 — shared PreCompact hook template installer (DRY across providers).
+export {
+  getProviderHookTemplatePath,
+  getSharedHookCorePath,
+  installProviderHookTemplates,
+} from './providers/shared/hook-template-installer.js';
 export type { AdapterManifest } from './registry.js';
 export { discoverProviders, getProviderManifests } from './registry.js';

package/src/providers/README.md

@@ -0,0 +1,137 @@
+# CLEO Provider Adapters
+
+This directory contains the per-provider adapters that integrate CLEO with
+individual AI coding harnesses (Claude Code, Cursor, OpenCode, Gemini CLI,
+Pi, etc.). Each adapter implements the contracts defined in
+`@cleocode/contracts` and delegates universal behaviour to CLEO core through
+the `cleo` CLI — adapters never reach into `@cleocode/core` internals at
+runtime.
+
+## Directory layout
+
+```
+providers/
+├── claude-code/
+│   ├── adapter.ts         # CLEOProviderAdapter implementation
+│   ├── hooks.ts           # AdapterHookProvider (event-name translation)
+│   ├── install.ts         # AdapterInstallProvider (filesystem wiring)
+│   ├── spawn.ts           # AdapterSpawnProvider
+│   └── templates/
+│       └── hooks/         # Provider-specific shell shims  (see below)
+├── cursor/
+│   ├── ...
+│   └── templates/hooks/
+├── opencode/
+│   ├── ...
+│   └── templates/hooks/
+├── gemini-cli/
+│   ├── ...
+│   └── templates/hooks/
+├── pi/
+│   ├── ...
+│   └── templates/hooks/   # README only — Pi uses TS extensions, not shell
+└── shared/
+    ├── hook-template-installer.ts   # DRY installer for all providers
+    ├── paths.ts
+    ├── transcript-reader.ts
+    └── templates/hooks/
+        └── cleo-precompact-core.sh  # Shared universal helper (single SSoT)
+```
+
+## Hook Template Architecture (T1013)
+
+The provider adapters own all harness-specific hook templates. The core
+package (`@cleocode/core`) ships only the universal business logic
+(`src/memory/precompact-flush.ts`, `src/hooks/handlers/*`) and the `cleo`
+CLI — never bash.
+
+### Layered design
+
+1. **Universal layer** — `shared/templates/hooks/cleo-precompact-core.sh`
+   contains the one-and-only implementation of the pre-compact flush +
+   safestop sequence. It invokes the CLEO CLI (`cleo memory precompact-flush`
+   and `cleo safestop …`). No provider knows any CLEO internals; every
+   provider ends up at the same CLI surface.
+
+2. **Provider shim layer** — each harness-specific directory ships a tiny
+   wrapper that sources the universal helper and adds only provider-flavoured
+   banners / env handling. Per-provider filenames match the harness's native
+   event vocabulary:
+
+   | Provider     | Shim                                    | Canonical event | Native event              |
+   |--------------|-----------------------------------------|-----------------|---------------------------|
+   | claude-code  | `precompact-safestop.sh`                | `PreCompact`    | `PreCompact`              |
+   | cursor       | `precompact.sh`                         | `PreCompact`    | `preCompact`              |
+   | opencode     | `precompact.sh` + `cleo-precompact.js`  | `PreCompact`    | `experimental.session.compacting` |
+   | gemini-cli   | `precompact.sh`                         | `PreCompact`    | `PreCompress`             |
+   | pi           | *README-only* (uses TS extension)       | `PreCompact`    | `context`                 |
+
+   The event mappings are sourced from `packages/caamp/providers/hook-mappings.json`
+   (the CAAMP SSoT). Provider adapters import the translation via
+   `@cleocode/caamp`'s `toNative()` / `getProviderHookProfile()` APIs rather
+   than hardcoding names.
+
+3. **Installer layer** — `shared/hook-template-installer.ts` exposes a single
+   `installProviderHookTemplates({ provider, targetDir })` function that:
+     1. Resolves the provider's shim + the shared helper from this package.
+     2. Copies both into the provided target directory (idempotent).
+     3. Returns an install summary for reporting.
+
+   Each provider's `AdapterInstallProvider.install(...)` method calls this
+   installer and then wires the shim into the harness's configuration
+   surface:
+
+     - Claude Code: append a `PreCompact` entry to `~/.claude/settings.json`.
+     - Cursor: append a `preCompact` entry to `.cursor/hooks.json`.
+     - OpenCode: generate a JS plugin at
+       `.opencode/plugins/cleo-precompact.js` that `spawn()`s the shim.
+     - Gemini CLI: (planned) append a `PreCompress` entry to
+       `~/.gemini/settings.json`.
+     - Pi: (planned) write a TS extension that calls the core handler.
+
+### Why this split?
+
+Before T1013 the pre-compact hook lived in
+`packages/core/templates/hooks/precompact-safestop.sh` — Claude-Code-specific
+bash buried inside the provider-neutral core package. Moving the file into
+`packages/adapters/src/providers/claude-code/templates/hooks/` and adding
+equivalent templates under the other provider directories restores the
+architectural boundary:
+
+- **Core** owns universal CLEO logic (`precompact-flush.ts`,
+  `memory-sqlite.ts`, session handling).
+- **Adapters** own harness-specific wiring (shell shims, config fragments,
+  plugin generators).
+- **CAAMP** owns the event-name translation SSoT (`hook-mappings.json`).
+
+Provider adapters are the only place that knows whether a harness uses
+`.claude/settings.json` versus `.cursor/hooks.json` versus a JS plugin —
+and they all funnel execution back through the same `cleo` CLI.
+
+### Adding a new harness
+
+1. Add the provider's mapping to `packages/caamp/providers/hook-mappings.json`
+   (the SSoT). At minimum populate `hookSystem`, `hookConfigPath`,
+   `handlerTypes`, and the `PreCompact` entry under `mappings`.
+2. Create `<provider>/templates/hooks/<shim>.sh` that sources the shared
+   helper. Keep the shim small — only provider-flavoured echo / exit handling
+   goes here.
+3. Teach `shared/hook-template-installer.ts` about the new provider id by
+   adding it to `HookTemplateProviderId` and `PROVIDER_SHIM`.
+4. Add the provider's `AdapterInstallProvider` method that calls
+   `installProviderHookTemplates` + writes the harness-specific config
+   fragment.
+5. Ship tests under `<provider>/__tests__/hooks-install.test.ts`.
+
+### Constraints
+
+- **Shims MUST invoke CLEO only through the CLI.** No `require('@cleocode/core')`,
+  no reaching into core internals from bash.
+- **Shims MUST be idempotent on install and uninstall.** Re-running the
+  installer must not duplicate config entries.
+- **The shared helper is the one-and-only contract.** Duplicating its logic
+  into provider shims is a DRY violation — add provider-specific behaviour
+  only to the shim wrapper.
+- **Hook failures MUST NOT block the harness.** All CLEO invocations in the
+  shim tolerate non-zero exits via `|| true` so the host compaction path is
+  never interrupted.

package/src/providers/claude-code/__tests__/hooks-install.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for the Claude Code PreCompact hook-template installer (T1013).
+ *
+ * Validates that:
+ * - Shared `cleo-precompact-core.sh` and provider-specific
+ *   `precompact-safestop.sh` are copied into `~/.claude/hooks/`.
+ * - `~/.claude/settings.json` gains a `PreCompact` entry pointing at the
+ *   installed shim, tagged with the `# cleo-hook` sentinel for clean uninstall.
+ * - Repeat invocations are idempotent (no duplicate settings entries).
+ * - The source templates contain the universal CLEO CLI invocations so the
+ *   bash contract remains DRY across providers.
+ *
+ * The tests use real filesystem writes under a scoped tmp directory that
+ * impersonates `$HOME` via the `HOME` env var, so no user config is touched.
+ *
+ * @task T1013
+ * @epic T1000
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ClaudeCodeInstallProvider } from '../install.js';
+
+describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
+  let fakeHome: string;
+  let realHome: string | undefined;
+  let projectDir: string;
+
+  beforeEach(() => {
+    realHome = process.env.HOME;
+    fakeHome = mkdtempSync(join(tmpdir(), 'cleo-claude-install-'));
+    projectDir = mkdtempSync(join(tmpdir(), 'cleo-claude-project-'));
+    process.env.HOME = fakeHome;
+    // Suppress unused-var lint on Windows (USERPROFILE pathway not exercised here).
+    void fakeHome;
+  });
+
+  afterEach(() => {
+    if (realHome !== undefined) {
+      process.env.HOME = realHome;
+    } else {
+      delete process.env.HOME;
+    }
+    rmSync(fakeHome, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('installs both bash templates into $HOME/.claude/hooks/', async () => {
+    const provider = new ClaudeCodeInstallProvider();
+
+    const result = await provider.install({ projectDir });
+    expect(result.success).toBe(true);
+
+    const hookTemplates = (result.details?.hookTemplates ?? null) as {
+      templates: { installedFiles: string[]; targetDir: string };
+      settingsEntryAdded: boolean;
+    } | null;
+
+    expect(hookTemplates).not.toBeNull();
+    expect(hookTemplates?.templates.targetDir).toBe(join(fakeHome, '.claude', 'hooks'));
+    const installed = hookTemplates?.templates.installedFiles ?? [];
+    expect(installed.some((p) => p.endsWith('cleo-precompact-core.sh'))).toBe(true);
+    expect(installed.some((p) => p.endsWith('precompact-safestop.sh'))).toBe(true);
+
+    // Installed shim sources the shared helper.
+    const shim = readFileSync(
+      join(fakeHome, '.claude', 'hooks', 'precompact-safestop.sh'),
+      'utf-8',
+    );
+    expect(shim).toContain('cleo-precompact-core.sh');
+    // Shared helper invokes the universal CLEO CLI.
+    const core = readFileSync(
+      join(fakeHome, '.claude', 'hooks', 'cleo-precompact-core.sh'),
+      'utf-8',
+    );
+    expect(core).toContain('cleo memory precompact-flush');
+    expect(core).toContain('cleo');
+    expect(core).toMatch(/cleo_cmd.*safestop/);
+  });
+
+  it('writes a PreCompact entry into $HOME/.claude/settings.json tagged # cleo-hook', async () => {
+    const provider = new ClaudeCodeInstallProvider();
+    await provider.install({ projectDir });
+
+    const settingsPath = join(fakeHome, '.claude', 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
+      hooks?: Record<string, Array<{ hooks?: Array<{ command?: string; type?: string }> }>>;
+    };
+
+    const preCompact = settings.hooks?.PreCompact ?? [];
+    expect(preCompact.length).toBeGreaterThan(0);
+    const firstEntry = preCompact[0];
+    expect(firstEntry).toBeDefined();
+    const firstHook = firstEntry?.hooks?.[0];
+    expect(firstHook?.type).toBe('command');
+    expect(firstHook?.command).toContain('precompact-safestop.sh');
+    expect(firstHook?.command).toContain('# cleo-hook');
+  });
+
+  it('is idempotent — re-running install does not duplicate the PreCompact entry', async () => {
+    const provider = new ClaudeCodeInstallProvider();
+    await provider.install({ projectDir });
+    await provider.install({ projectDir });
+
+    const settingsPath = join(fakeHome, '.claude', 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
+      hooks?: { PreCompact?: unknown[] };
+    };
+    expect((settings.hooks?.PreCompact ?? []).length).toBe(1);
+  });
+});