@cleocode/caamp 2026.4.9 → 2026.4.11

package/dist/index.d.ts

@@ -2807,6 +2807,14 @@ declare function setExclusivityMode(mode: ExclusivityMode): void;
  * environment variable (and falls back to the default when the env var is
  * unset or invalid). Idempotent — safe to call when no override is active.
  *
+ * @example
+ * ```typescript
+ * setExclusivityMode("force-pi");
+ * // ...run test...
+ * resetExclusivityModeOverride();
+ * // getExclusivityMode() now reads CAAMP_EXCLUSIVITY_MODE again
+ * ```
+ *
  * @public
  */
 declare function resetExclusivityModeOverride(): void;
@@ -3122,15 +3130,27 @@ declare class PiHarness implements Harness {
      * auto-discovering `AGENTS.md` from the working directory upwards.
      */
     private agentsMdPath;
-    /** {@inheritDoc Harness.installSkill} */
+    /**
+     * Install a skill directory into the resolved Pi skills location.
+     */
     installSkill(sourcePath: string, skillName: string, scope: HarnessScope): Promise<void>;
-    /** {@inheritDoc Harness.removeSkill} */
+    /**
+     * Remove a skill directory from the resolved Pi skills location.
+     */
     removeSkill(skillName: string, scope: HarnessScope): Promise<void>;
-    /** {@inheritDoc Harness.listSkills} */
+    /**
+     * List the installed skill directories at the given scope.
+     */
     listSkills(scope: HarnessScope): Promise<string[]>;
-    /** {@inheritDoc Harness.injectInstructions} */
+    /**
+     * Inject or replace a CAAMP-managed instruction block inside the Pi
+     * `AGENTS.md` file for the resolved scope.
+     */
     injectInstructions(content: string, scope: HarnessScope): Promise<void>;
-    /** {@inheritDoc Harness.removeInstructions} */
+    /**
+     * Remove the CAAMP-managed instruction block from the Pi `AGENTS.md`
+     * file at the resolved scope.
+     */
     removeInstructions(scope: HarnessScope): Promise<void>;
     /**
      * Spawn a subagent through Pi's configured `spawnCommand` and return a
@@ -3245,11 +3265,19 @@ declare class PiHarness implements Harness {
      * length entry that has no semantic meaning).
      */
     private handleStdoutLine;
-    /** {@inheritDoc Harness.readSettings} */
+    /**
+     * Read the Pi `settings.json` file for the resolved scope.
+     */
     readSettings(scope: HarnessScope): Promise<unknown>;
-    /** {@inheritDoc Harness.writeSettings} */
+    /**
+     * Merge a partial patch into the Pi `settings.json` file for the
+     * resolved scope using an atomic write.
+     */
     writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
-    /** {@inheritDoc Harness.configureModels} */
+    /**
+     * Persist the supplied model-name patterns into `settings.enabledModels`
+     * at the resolved scope.
+     */
     configureModels(modelPatterns: string[], scope: HarnessScope): Promise<void>;
     /**
      * Resolve the `models.json` path for a given legacy two-tier scope.
@@ -3266,67 +3294,109 @@ declare class PiHarness implements Harness {
      * the single authoritative location per ADR-035 §D2.
      */
     private sessionsDir;
-    /** {@inheritDoc Harness.installExtension} */
+    /**
+     * Install a Pi extension `.ts` source file into the resolved tier's
+     * extensions directory, validating that it has a default export.
+     */
     installExtension(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
         targetPath: string;
         tier: HarnessTier;
     }>;
-    /** {@inheritDoc Harness.removeExtension} */
+    /**
+     * Remove a Pi extension `.ts` source file from the resolved tier.
+     */
     removeExtension(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
-    /** {@inheritDoc Harness.listExtensions} */
+    /**
+     * List Pi extension files across every tier in precedence order,
+     * flagging shadowed entries from lower tiers.
+     */
     listExtensions(projectDir?: string): Promise<ExtensionEntry[]>;
-    /** {@inheritDoc Harness.listSessions} */
+    /**
+     * List Pi session JSONL files (including subagent children when
+     * requested), summarising only the header line per file.
+     */
     listSessions(opts?: {
         includeSubagents?: boolean;
     }): Promise<SessionSummary[]>;
-    /** {@inheritDoc Harness.showSession} */
+    /**
+     * Show the full entries of a single Pi session by id.
+     */
     showSession(id: string): Promise<SessionDocument>;
-    /** {@inheritDoc Harness.readModelsConfig} */
+    /**
+     * Read the Pi `models.json` file for the resolved scope, tolerating
+     * missing or malformed files by returning an empty provider map.
+     */
     readModelsConfig(scope: HarnessScope): Promise<PiModelsConfig>;
-    /** {@inheritDoc Harness.writeModelsConfig} */
+    /**
+     * Write the Pi `models.json` file for the resolved scope via an atomic
+     * tmp-then-rename sequence.
+     */
     writeModelsConfig(config: PiModelsConfig, scope: HarnessScope): Promise<void>;
-    /** {@inheritDoc Harness.listModels} */
+    /**
+     * Compose a flat `ModelListEntry` list from `models.json` plus the
+     * `enabledModels` and default-model hints in `settings.json`.
+     */
     listModels(scope: HarnessScope): Promise<ModelListEntry[]>;
-    /** {@inheritDoc Harness.installPrompt} */
+    /**
+     * Install a Pi prompt directory (containing `prompt.md`) into the
+     * resolved tier's prompts directory.
+     */
     installPrompt(sourceDir: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
         targetPath: string;
         tier: HarnessTier;
     }>;
-    /** {@inheritDoc Harness.listPrompts} */
+    /**
+     * List Pi prompt directories across every tier in precedence order,
+     * flagging shadowed entries from lower tiers.
+     */
     listPrompts(projectDir?: string): Promise<PromptEntry[]>;
-    /** {@inheritDoc Harness.removePrompt} */
+    /**
+     * Remove a Pi prompt directory from the resolved tier.
+     */
     removePrompt(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
-    /** {@inheritDoc Harness.installTheme} */
+    /**
+     * Install a Pi theme file (`.ts`/`.tsx`/`.mts`/`.json`) into the
+     * resolved tier's themes directory, blocking same-stem conflicts
+     * unless `--force` is supplied.
+     */
     installTheme(sourceFile: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
         targetPath: string;
         tier: HarnessTier;
     }>;
-    /** {@inheritDoc Harness.listThemes} */
+    /**
+     * List Pi theme files across every tier in precedence order, flagging
+     * shadowed entries from lower tiers.
+     */
     listThemes(projectDir?: string): Promise<ThemeEntry[]>;
-    /** {@inheritDoc Harness.removeTheme} */
+    /**
+     * Remove a Pi theme from the resolved tier, matching any of the
+     * supported theme extensions for the given name stem.
+     */
     removeTheme(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
     /**
-     * {@inheritDoc Harness.installCantProfile}
+     * Install a `.cant` profile into the resolved tier after passing it
+     * through the cant-core validator.
      *
-     * @remarks
-     * Validates the source via {@link validateCantProfile} before copying so
-     * we never persist a `.cant` file the runtime bridge cannot load. The
-     * target layout is `<tier-root>/cant/<name>.cant`, resolved through
-     * {@link resolveTierDir} so the project/user/global hierarchy stays
-     * consistent with the other Wave-1 verbs.
+     * Validates the source via {@link PiHarness.validateCantProfile}
+     * before copying so we never persist a `.cant` file the runtime bridge
+     * cannot load. The target layout is `<tier-root>/cant/<name>.cant`,
+     * resolved through `resolveTierDir` so the project/user/global
+     * hierarchy stays consistent with the other Wave-1 verbs.
      */
     installCantProfile(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
         targetPath: string;
         tier: HarnessTier;
         counts: CantProfileCounts;
     }>;
-    /** {@inheritDoc Harness.removeCantProfile} */
+    /**
+     * Remove a `.cant` profile from the resolved tier.
+     */
     removeCantProfile(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
     /**
-     * {@inheritDoc Harness.listCantProfiles}
+     * List installed `.cant` profiles across every tier in precedence
+     * order, parsing each file to extract section counts.
      *
-     * @remarks
-     * Walks every tier in {@link TIER_PRECEDENCE} order, parsing each
+     * Walks every tier in `TIER_PRECEDENCE` order, parsing each
      * discovered `.cant` file via cant-core to extract a
      * {@link CantProfileCounts} bag. Higher-precedence tiers shadow
      * lower-precedence entries with the same name; shadowed entries
@@ -3336,9 +3406,9 @@ declare class PiHarness implements Harness {
      */
     listCantProfiles(projectDir?: string): Promise<CantProfileEntry[]>;
     /**
-     * {@inheritDoc Harness.validateCantProfile}
+     * Validate a `.cant` source file against cant-core's parser and
+     * 42-rule linter, returning section counts and per-diagnostic detail.
      *
-     * @remarks
      * Pure validator. Reads the file, runs `parseDocument` to derive
      * counts (when parsing succeeds) and `validateDocument` to collect
      * the 42-rule diagnostic feed. The two calls are kept independent so
@@ -3422,6 +3492,13 @@ declare function getPrimaryHarness(): Harness | null;
  * @returns Array of harness instances, one per provider that implements
  * the {@link Harness} contract.
  *
+ * @example
+ * ```typescript
+ * for (const harness of getAllHarnesses()) {
+ *   console.log(harness.provider.id); // "pi", ...
+ * }
+ * ```
+ *
  * @public
  */
 declare function getAllHarnesses(): Harness[];
@@ -3444,8 +3521,9 @@ declare function getAllHarnesses(): Harness[];
  * dispatchers ({@link dispatchInstallSkillAcrossProviders},
  * {@link dispatchRemoveSkillAcrossProviders}) intentionally do not call
  * this function — they target every requested provider directly so that
- * users in `force-pi` mode can still `caamp skills install foo --agent
- * claude-code` while Pi is being installed.
+ * users in `force-pi` mode can still run
+ * `caamp skills install foo --agent claude-code` while Pi is being
+ * installed.
  *
  * The helper is intentionally defensive: registry/detection exceptions
  * are caught and treated as "Pi unknown" so stubbed test environments
@@ -4865,6 +4943,13 @@ interface McpDetectionEntry {
  * @param projectDir - Project directory used for the `project` scope.
  * @returns The absolute config file path, or `null` when unavailable.
  *
+ * @example
+ * ```typescript
+ * const claudeCode = getProvider("claude-code")!;
+ * const path = resolveMcpConfigPath(claudeCode, "project", "/tmp/app");
+ * // e.g. "/tmp/app/.mcp.json"
+ * ```
+ *
  * @public
  */
 declare function resolveMcpConfigPath(provider: Provider, scope: McpScope, projectDir?: string): string | null;
@@ -4896,6 +4981,15 @@ declare function resolveMcpConfigPath(provider: Provider, scope: McpScope, proje
  *   (defaults to `process.cwd()`).
  * @returns Array of MCP server entries, or `[]` when nothing was found.
  *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code")!;
+ * const entries = await listMcpServers(provider, "project");
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.configPath);
+ * }
+ * ```
+ *
  * @public
  */
 declare function listMcpServers(provider: Provider, scope: McpScope, projectDir?: string): Promise<McpServerEntry[]>;
@@ -4930,6 +5024,14 @@ type McpServerEntriesByProvider = Map<string, McpServerEntry[]>;
  * @param projectDir - Project directory used for the `project` scope.
  * @returns Map of provider id → server entries.
  *
+ * @example
+ * ```typescript
+ * const byProvider = await listAllMcpServers("global");
+ * for (const [providerId, entries] of byProvider) {
+ *   console.log(`${providerId}: ${entries.length} server(s)`);
+ * }
+ * ```
+ *
  * @public
  */
 declare function listAllMcpServers(scope: McpScope, projectDir?: string): Promise<McpServerEntriesByProvider>;
@@ -4948,6 +5050,13 @@ declare function listAllMcpServers(scope: McpScope, projectDir?: string): Promis
  * @param projectDir - Project directory used for the `project` scope.
  * @returns Array of detection entries, one per MCP-capable provider.
  *
+ * @example
+ * ```typescript
+ * const hits = await detectMcpInstallations("project");
+ * const installed = hits.filter((h) => h.exists);
+ * console.log(`MCP found on ${installed.length} providers`);
+ * ```
+ *
  * @public
  */
 declare function detectMcpInstallations(scope: McpScope, projectDir?: string): Promise<McpDetectionEntry[]>;
@@ -5038,6 +5147,18 @@ interface InstallMcpServerResult {
  * @throws `Error` when the provider has no MCP capability or no
  *   project-scoped config path is available.
  *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code")!;
+ * const result = await installMcpServer(
+ *   provider,
+ *   "github",
+ *   { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+ *   { scope: "project", force: false },
+ * );
+ * console.log(result.installed, result.conflicted);
+ * ```
+ *
  * @public
  */
 declare function installMcpServer(provider: Provider, serverName: string, config: McpServerConfig, opts: InstallMcpServerOptions): Promise<InstallMcpServerResult>;
@@ -5116,6 +5237,13 @@ interface RemoveMcpServerResult {
  * @param opts - Removal options.
  * @returns Structured result describing whether the entry was removed.
  *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code")!;
+ * const result = await removeMcpServer(provider, "my-server", { scope: "project" });
+ * console.log(result.removed); // true | false
+ * ```
+ *
  * @public
  */
 declare function removeMcpServer(provider: Provider, serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult>;
@@ -5135,6 +5263,13 @@ declare function removeMcpServer(provider: Provider, serverName: string, opts: R
  * @param opts - Removal options applied uniformly to every provider.
  * @returns Array of per-provider removal results.
  *
+ * @example
+ * ```typescript
+ * const results = await removeMcpServerFromAll("my-server", { scope: "global" });
+ * const removed = results.filter((r) => r.removed);
+ * console.log(`Removed from ${removed.length} providers`);
+ * ```
+ *
  * @public
  */
 declare function removeMcpServerFromAll(serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult[]>;

package/dist/index.js

@@ -70,7 +70,7 @@ import {
   validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-JC77OAHA.js";
+} from "./chunk-XVZT7K6F.js";
 import {
   buildInjectionContent,
   buildSkillsMap,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/caamp",
-  "version": "2026.4.9",
+  "version": "2026.4.11",
   "description": "Central AI Agent Managed Packages - unified provider registry and package manager for AI coding agents",
   "type": "module",
   "bin": {
@@ -51,11 +51,12 @@
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
     "simple-git": "3.33.0",
-    "@cleocode/cant": "2026.4.9",
-    "@cleocode/lafs": "2026.4.9"
+    "@cleocode/cant": "2026.4.11",
+    "@cleocode/lafs": "2026.4.11"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.8",
+    "@forge-ts/cli": "0.23.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "25.5.0",
     "@vitest/coverage-v8": "^4.1.0",
@@ -83,6 +84,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome lint src tests",
     "lint:fix": "biome lint --write src tests",
+    "docs": "forge-ts check && forge-ts build --skip-api",
+    "docs:check": "forge-ts check",
     "docs:api": "typedoc",
     "docs:api:check": "typedoc --emit none",
     "research": "tsx scripts/provider-research.ts"