@cleocode/paths 2026.5.28 → 2026.5.33

package/dist/cleo-paths.d.ts

@@ -56,6 +56,33 @@ export declare function getCleoSystemInfo(): SystemInfo;
  * @public
  */
 export declare function getCleoTemplatesTildePath(): string;
+/**
+ * Get the CLEO templates directory as a stable tilde-prefixed path for use in
+ * `@`-references written into shared files (e.g. `~/.agents/AGENTS.md`).
+ *
+ * Unlike {@link getCleoTemplatesTildePath}, this function is **immune to
+ * `CLEO_HOME` overrides**. It derives the reference from `homedir()` alone
+ * via the canonical `~/.cleo` symlink path, which is always stable regardless
+ * of the current `CLEO_HOME` env var value.
+ *
+ * This is the correct function to use when writing a template reference into
+ * a file that persists across sessions (e.g. the global `~/.agents/AGENTS.md`
+ * hub). Using {@link getCleoTemplatesTildePath} there causes test environments
+ * — which override `CLEO_HOME` to a temp directory — to write stale temp-path
+ * blocks into the real AGENTS.md on every test run (T9020 / T1929).
+ *
+ * @returns `"~/.cleo/templates"` on all platforms — resolves via the `~/.cleo`
+ *   symlink to the OS-appropriate canonical data directory at runtime.
+ *
+ * @example
+ * ```typescript
+ * const ref = `@${getCanonicalTemplatesTildePath()}/CLEO-INJECTION.md`;
+ * // "@~/.cleo/templates/CLEO-INJECTION.md"
+ * ```
+ *
+ * @public
+ */
+export declare function getCanonicalTemplatesTildePath(): string;
 /**
  * Invalidate the cached CLEO system info snapshot. Use in tests after
  * mutating `CLEO_HOME` or related env vars.

package/dist/cleo-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleo-paths.d.ts","sourceRoot":"","sources":["../src/cleo-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAM7B;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAQlD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}
+{"version":3,"file":"cleo-paths.d.ts","sourceRoot":"","sources":["../src/cleo-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAM7B;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAQlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CAMvD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/cleo-paths.js

@@ -74,6 +74,39 @@ export function getCleoTemplatesTildePath() {
     }
     return absPath;
 }
+/**
+ * Get the CLEO templates directory as a stable tilde-prefixed path for use in
+ * `@`-references written into shared files (e.g. `~/.agents/AGENTS.md`).
+ *
+ * Unlike {@link getCleoTemplatesTildePath}, this function is **immune to
+ * `CLEO_HOME` overrides**. It derives the reference from `homedir()` alone
+ * via the canonical `~/.cleo` symlink path, which is always stable regardless
+ * of the current `CLEO_HOME` env var value.
+ *
+ * This is the correct function to use when writing a template reference into
+ * a file that persists across sessions (e.g. the global `~/.agents/AGENTS.md`
+ * hub). Using {@link getCleoTemplatesTildePath} there causes test environments
+ * — which override `CLEO_HOME` to a temp directory — to write stale temp-path
+ * blocks into the real AGENTS.md on every test run (T9020 / T1929).
+ *
+ * @returns `"~/.cleo/templates"` on all platforms — resolves via the `~/.cleo`
+ *   symlink to the OS-appropriate canonical data directory at runtime.
+ *
+ * @example
+ * ```typescript
+ * const ref = `@${getCanonicalTemplatesTildePath()}/CLEO-INJECTION.md`;
+ * // "@~/.cleo/templates/CLEO-INJECTION.md"
+ * ```
+ *
+ * @public
+ */
+export function getCanonicalTemplatesTildePath() {
+    // Always return the stable ~/.cleo symlink path. This symlink is created by
+    // bootstrapGlobalCleo() and always points to the OS-appropriate canonical data
+    // directory (e.g. ~/.local/share/cleo on Linux). Using this path here ensures
+    // that CLEO_HOME overrides in test environments do NOT pollute shared files.
+    return '~/.cleo/templates';
+}
 /**
  * Invalidate the cached CLEO system info snapshot. Use in tests after
  * mutating `CLEO_HOME` or related env vars.

package/dist/cleo-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"cleo-paths.js","sourceRoot":"","sources":["../src/cleo-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,2BAA2B,GAG5B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAErC,MAAM,YAAY,GAAG,2BAA2B,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,gBAAgB,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,YAAY,CAAC,aAAa,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChE,OAAO,IAAI,QAAQ,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B;IAC1C,YAAY,CAAC,UAAU,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"cleo-paths.js","sourceRoot":"","sources":["../src/cleo-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,2BAA2B,GAG5B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAErC,MAAM,YAAY,GAAG,2BAA2B,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,gBAAgB,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,YAAY,CAAC,aAAa,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChE,OAAO,IAAI,QAAQ,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,8BAA8B;IAC5C,4EAA4E;IAC5E,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B;IAC1C,YAAY,CAAC,UAAU,EAAE,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -19,7 +19,7 @@
  * @task T1883
  */
 export { isAbsolutePath } from './abs-path.js';
-export { _resetCleoPlatformPathsCache, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, } from './cleo-paths.js';
+export { _resetCleoPlatformPathsCache, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, } from './cleo-paths.js';
 export { createPlatformPathsResolver, type PlatformPaths, type PlatformPathsResolver, type SystemInfo, } from './platform-paths.js';
 export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeRootForHash, } from './worktree-paths.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -19,7 +19,7 @@
  * @task T1883
  */
 export { isAbsolutePath } from './abs-path.js';
-export { _resetCleoPlatformPathsCache, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, } from './cleo-paths.js';
+export { _resetCleoPlatformPathsCache, getCanonicalTemplatesTildePath, getCleoHome, getCleoPlatformPaths, getCleoSystemInfo, getCleoTemplatesTildePath, } from './cleo-paths.js';
 export { createPlatformPathsResolver, } from './platform-paths.js';
 export { computeProjectHash, getCleoWorktreesRoot, resolveTaskWorktreePath, resolveWorktreeRootForHash, } from './worktree-paths.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAI5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAI5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/paths",
-  "version": "2026.5.28",
+  "version": "2026.5.33",
   "private": false,
   "type": "module",
   "description": "CLEO XDG/env-paths SSoT — createPlatformPathsResolver factory, cleo-bound platform paths, project hash + worktree root primitives, isAbsolutePath. Zero-dep leaf package consumed by core, worktree, brain, adapters, and caamp.",