@cleocode/paths 2026.5.26

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLEO Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/abs-path.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-platform absolute path detection.
+ *
+ * Recognises POSIX absolute paths (`/...`), Windows drive letters (`C:\...`,
+ * `D:/...`), and UNC paths (`\\server\share`). Used in path-resolution code
+ * that needs to short-circuit when given an already-absolute path without
+ * importing the heavier `node:path#isAbsolute`.
+ *
+ * @task T1883
+ */
+/**
+ * Check if a path is absolute on any supported platform.
+ *
+ * @param path - Filesystem path to check.
+ * @returns `true` for POSIX absolute, Windows drive-rooted, or UNC paths.
+ *
+ * @example
+ * ```typescript
+ * isAbsolutePath('/usr/bin');     // true
+ * isAbsolutePath('C:\\Users');    // true
+ * isAbsolutePath('\\\\srv\\sh');  // true
+ * isAbsolutePath('./relative');   // false
+ * ```
+ *
+ * @public
+ */
+export declare function isAbsolutePath(path: string): boolean;
+//# sourceMappingURL=abs-path.d.ts.map

package/dist/abs-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abs-path.d.ts","sourceRoot":"","sources":["../src/abs-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD"}

package/dist/abs-path.js

@@ -0,0 +1,37 @@
+/**
+ * Cross-platform absolute path detection.
+ *
+ * Recognises POSIX absolute paths (`/...`), Windows drive letters (`C:\...`,
+ * `D:/...`), and UNC paths (`\\server\share`). Used in path-resolution code
+ * that needs to short-circuit when given an already-absolute path without
+ * importing the heavier `node:path#isAbsolute`.
+ *
+ * @task T1883
+ */
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/;
+/**
+ * Check if a path is absolute on any supported platform.
+ *
+ * @param path - Filesystem path to check.
+ * @returns `true` for POSIX absolute, Windows drive-rooted, or UNC paths.
+ *
+ * @example
+ * ```typescript
+ * isAbsolutePath('/usr/bin');     // true
+ * isAbsolutePath('C:\\Users');    // true
+ * isAbsolutePath('\\\\srv\\sh');  // true
+ * isAbsolutePath('./relative');   // false
+ * ```
+ *
+ * @public
+ */
+export function isAbsolutePath(path) {
+    if (path.startsWith('/'))
+        return true;
+    if (WINDOWS_DRIVE_RE.test(path))
+        return true;
+    if (path.startsWith('\\\\'))
+        return true;
+    return false;
+}
+//# sourceMappingURL=abs-path.js.map

package/dist/abs-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abs-path.js","sourceRoot":"","sources":["../src/abs-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/cleo-paths.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CLEO-bound platform path helpers.
+ *
+ * Pre-binds {@link createPlatformPathsResolver} to `(appName='cleo', homeEnvVar='CLEO_HOME')`
+ * and exposes the cleo-specific helpers every other CLEO package needs:
+ * `getCleoHome`, `getCleoPlatformPaths`, `getCleoSystemInfo`, and
+ * `getCleoTemplatesTildePath`.
+ *
+ * @task T1883
+ */
+import { type PlatformPaths, type SystemInfo } from './platform-paths.js';
+/**
+ * Get OS-appropriate paths for CLEO's global directories.
+ *
+ * Linux:   `~/.local/share/cleo` | macOS: `~/Library/Application Support/cleo`
+ * Windows: `%LOCALAPPDATA%\cleo\Data`
+ *
+ * The `CLEO_HOME` env var overrides the `data` field. Read fresh on every call.
+ *
+ * @public
+ */
+export declare function getCleoPlatformPaths(): PlatformPaths;
+/**
+ * Get the absolute path to CLEO's global data directory.
+ *
+ * Equivalent to `getCleoPlatformPaths().data` — exposed as a stable named
+ * helper because `getCleoHome()` is the most common consumer call.
+ *
+ * @public
+ */
+export declare function getCleoHome(): string;
+/**
+ * Get a cached system information snapshot scoped to CLEO.
+ *
+ * Includes platform, architecture, hostname, Node version, and resolved
+ * CLEO paths. Captured once per process and reused — invalidate via
+ * {@link _resetCleoPlatformPathsCache} in tests if needed.
+ *
+ * @public
+ */
+export declare function getCleoSystemInfo(): SystemInfo;
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use in
+ * `@`-references (AGENTS.md, CLAUDE.md, etc.). Cross-platform: replaces
+ * the user's home directory with `~` so the reference resolves consistently
+ * when an LLM provider expands `~` at runtime.
+ *
+ * @returns Tilde-prefixed path like `"~/.local/share/cleo/templates"` on Linux
+ *
+ * @example
+ * ```typescript
+ * const ref = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+ * // "@~/.local/share/cleo/templates/CLEO-INJECTION.md"  (Linux)
+ * ```
+ *
+ * @public
+ */
+export declare function getCleoTemplatesTildePath(): string;
+/**
+ * Invalidate the cached CLEO system info snapshot. Use in tests after
+ * mutating `CLEO_HOME` or related env vars.
+ *
+ * @internal
+ */
+export declare function _resetCleoPlatformPathsCache(): void;
+//# sourceMappingURL=cleo-paths.d.ts.map

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

@@ -0,0 +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"}

package/dist/cleo-paths.js

@@ -0,0 +1,86 @@
+/**
+ * CLEO-bound platform path helpers.
+ *
+ * Pre-binds {@link createPlatformPathsResolver} to `(appName='cleo', homeEnvVar='CLEO_HOME')`
+ * and exposes the cleo-specific helpers every other CLEO package needs:
+ * `getCleoHome`, `getCleoPlatformPaths`, `getCleoSystemInfo`, and
+ * `getCleoTemplatesTildePath`.
+ *
+ * @task T1883
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createPlatformPathsResolver, } from './platform-paths.js';
+const TEMPLATES_SUBDIR = 'templates';
+const cleoResolver = createPlatformPathsResolver('cleo', 'CLEO_HOME');
+/**
+ * Get OS-appropriate paths for CLEO's global directories.
+ *
+ * Linux:   `~/.local/share/cleo` | macOS: `~/Library/Application Support/cleo`
+ * Windows: `%LOCALAPPDATA%\cleo\Data`
+ *
+ * The `CLEO_HOME` env var overrides the `data` field. Read fresh on every call.
+ *
+ * @public
+ */
+export function getCleoPlatformPaths() {
+    return cleoResolver.getPlatformPaths();
+}
+/**
+ * Get the absolute path to CLEO's global data directory.
+ *
+ * Equivalent to `getCleoPlatformPaths().data` — exposed as a stable named
+ * helper because `getCleoHome()` is the most common consumer call.
+ *
+ * @public
+ */
+export function getCleoHome() {
+    return cleoResolver.getPlatformPaths().data;
+}
+/**
+ * Get a cached system information snapshot scoped to CLEO.
+ *
+ * Includes platform, architecture, hostname, Node version, and resolved
+ * CLEO paths. Captured once per process and reused — invalidate via
+ * {@link _resetCleoPlatformPathsCache} in tests if needed.
+ *
+ * @public
+ */
+export function getCleoSystemInfo() {
+    return cleoResolver.getSystemInfo();
+}
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use in
+ * `@`-references (AGENTS.md, CLAUDE.md, etc.). Cross-platform: replaces
+ * the user's home directory with `~` so the reference resolves consistently
+ * when an LLM provider expands `~` at runtime.
+ *
+ * @returns Tilde-prefixed path like `"~/.local/share/cleo/templates"` on Linux
+ *
+ * @example
+ * ```typescript
+ * const ref = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
+ * // "@~/.local/share/cleo/templates/CLEO-INJECTION.md"  (Linux)
+ * ```
+ *
+ * @public
+ */
+export function getCleoTemplatesTildePath() {
+    const absPath = join(getCleoHome(), TEMPLATES_SUBDIR);
+    const home = homedir();
+    if (absPath.startsWith(home)) {
+        const relative = absPath.slice(home.length).replace(/\\/g, '/');
+        return `~${relative}`;
+    }
+    return absPath;
+}
+/**
+ * Invalidate the cached CLEO system info snapshot. Use in tests after
+ * mutating `CLEO_HOME` or related env vars.
+ *
+ * @internal
+ */
+export function _resetCleoPlatformPathsCache() {
+    cleoResolver.resetCache();
+}
+//# sourceMappingURL=cleo-paths.js.map

package/dist/cleo-paths.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@cleocode/paths` — XDG / env-paths SSoT for the CLEO ecosystem.
+ *
+ * Zero-dep leaf package consumed by `@cleocode/core`, `@cleocode/worktree`,
+ * `@cleocode/brain`, `@cleocode/adapters`, and `@cleocode/caamp` to eliminate
+ * the env-paths and platform-path duplication that previously existed in
+ * each of those packages.
+ *
+ * Exposes:
+ * - {@link createPlatformPathsResolver} — generic factory bindable to any app
+ * - CLEO-bound helpers: {@link getCleoHome}, {@link getCleoPlatformPaths},
+ *   {@link getCleoSystemInfo}, {@link getCleoTemplatesTildePath}
+ * - Worktree primitives: {@link computeProjectHash},
+ *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
+ *   {@link getCleoWorktreesRoot}
+ * - {@link isAbsolutePath} — cross-platform abs-path check
+ *
+ * @packageDocumentation
+ * @task T1883
+ */
+export { isAbsolutePath } from './abs-path.js';
+export { _resetCleoPlatformPathsCache, 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

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@cleocode/paths` — XDG / env-paths SSoT for the CLEO ecosystem.
+ *
+ * Zero-dep leaf package consumed by `@cleocode/core`, `@cleocode/worktree`,
+ * `@cleocode/brain`, `@cleocode/adapters`, and `@cleocode/caamp` to eliminate
+ * the env-paths and platform-path duplication that previously existed in
+ * each of those packages.
+ *
+ * Exposes:
+ * - {@link createPlatformPathsResolver} — generic factory bindable to any app
+ * - CLEO-bound helpers: {@link getCleoHome}, {@link getCleoPlatformPaths},
+ *   {@link getCleoSystemInfo}, {@link getCleoTemplatesTildePath}
+ * - Worktree primitives: {@link computeProjectHash},
+ *   {@link resolveWorktreeRootForHash}, {@link resolveTaskWorktreePath},
+ *   {@link getCleoWorktreesRoot}
+ * - {@link isAbsolutePath} — cross-platform abs-path check
+ *
+ * @packageDocumentation
+ * @task T1883
+ */
+export { isAbsolutePath } from './abs-path.js';
+export { _resetCleoPlatformPathsCache, 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

@@ -0,0 +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"}

package/dist/platform-paths.d.ts

@@ -0,0 +1,113 @@
+/**
+ * OS platform-path resolver factory backed by `env-paths`.
+ *
+ * The factory is parameterised by `appName` + `homeEnvVar` so a single
+ * implementation serves every CLEO package that needs XDG-compliant
+ * paths — `cleo`, `agents` (CAAMP), or any future tool — without each
+ * package re-implementing the same env-paths wrapper, the same tilde
+ * expansion, and the same SystemInfo cache.
+ *
+ * `getPlatformPaths()` reads fresh on every call: env-paths is microsecond-fast
+ * and a process-wide cache would mask XDG / APPDATA env-var changes that test
+ * code legitimately makes. `getSystemInfo()` IS cached because hostname /
+ * platform / arch don't change during a process lifetime.
+ *
+ * @packageDocumentation
+ * @task T1883
+ */
+/**
+ * OS-appropriate directory paths for an application.
+ *
+ * Defaults follow XDG Base Directory on Linux, Apple's File System Programming
+ * Guide on macOS, and Microsoft's Known Folders on Windows. The home env-var
+ * passed to {@link createPlatformPathsResolver} overrides `data`.
+ *
+ * @public
+ */
+export interface PlatformPaths {
+    /** User data dir. Override with the configured home env var. */
+    data: string;
+    /** OS config dir (XDG_CONFIG_HOME / Library/Preferences / %APPDATA%). */
+    config: string;
+    /** OS cache dir. */
+    cache: string;
+    /** OS log dir. */
+    log: string;
+    /** OS temp dir. */
+    temp: string;
+}
+/**
+ * Snapshot of the current system environment combined with resolved platform paths.
+ *
+ * Cached for the process lifetime by {@link PlatformPathsResolver.getSystemInfo}.
+ *
+ * @public
+ */
+export interface SystemInfo {
+    /** Operating system platform identifier. */
+    platform: NodeJS.Platform;
+    /** CPU architecture (e.g. `"x64"`, `"arm64"`). */
+    arch: string;
+    /** OS kernel release version string. */
+    release: string;
+    /** Machine hostname. */
+    hostname: string;
+    /** Node.js version string (e.g. `"v24.0.0"`). */
+    nodeVersion: string;
+    /** Resolved platform directory paths. */
+    paths: PlatformPaths;
+}
+/**
+ * A platform-paths resolver bound to one app name + one home env var.
+ *
+ * Each resolver carries its own `SystemInfo` cache so resolvers for different
+ * apps (e.g. `cleo` vs `agents`) stay fully isolated.
+ *
+ * @public
+ */
+export interface PlatformPathsResolver {
+    /**
+     * Get OS-appropriate paths for the resolver's app directories.
+     *
+     * Reads fresh on every call. The home env var (when set) overrides the
+     * `data` field; `~`, `~/...`, absolute, and relative path values are all
+     * accepted and resolved against `homedir()`.
+     */
+    getPlatformPaths(): PlatformPaths;
+    /**
+     * Get a cached system information snapshot.
+     *
+     * Captured once per resolver and reused for the process lifetime. Includes
+     * platform, architecture, hostname, Node version, and resolved paths.
+     */
+    getSystemInfo(): SystemInfo;
+    /**
+     * Invalidate the cached system info snapshot. Use in tests after mutating
+     * the home env var.
+     *
+     * @internal
+     */
+    resetCache(): void;
+}
+/**
+ * Create a platform-paths resolver bound to a specific app name and home env var.
+ *
+ * Returns a resolver with its own internal `SystemInfo` cache. Path reads are
+ * always fresh (env-paths is fast); only system info is cached.
+ *
+ * @param appName - The application name passed to `env-paths` (e.g. `"cleo"`,
+ *   `"agents"`).
+ * @param homeEnvVar - The env var name that overrides the data directory
+ *   (e.g. `"CLEO_HOME"`, `"AGENTS_HOME"`). Tilde-prefixed and relative
+ *   values are resolved against `homedir()`.
+ *
+ * @example
+ * ```typescript
+ * const cleo = createPlatformPathsResolver('cleo', 'CLEO_HOME');
+ * cleo.getPlatformPaths().data; // → "/home/user/.local/share/cleo"  (Linux, no override)
+ * ```
+ *
+ * @public
+ */
+export declare function createPlatformPathsResolver(appName: string, homeEnvVar: string): PlatformPathsResolver;
+//# sourceMappingURL=platform-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"platform-paths.d.ts","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,gBAAgB,IAAI,aAAa,CAAC;IAElC;;;;;OAKG;IACH,aAAa,IAAI,UAAU,CAAC;IAE5B;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAC;CACpB;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,qBAAqB,CAiCvB"}

package/dist/platform-paths.js

@@ -0,0 +1,97 @@
+/**
+ * OS platform-path resolver factory backed by `env-paths`.
+ *
+ * The factory is parameterised by `appName` + `homeEnvVar` so a single
+ * implementation serves every CLEO package that needs XDG-compliant
+ * paths — `cleo`, `agents` (CAAMP), or any future tool — without each
+ * package re-implementing the same env-paths wrapper, the same tilde
+ * expansion, and the same SystemInfo cache.
+ *
+ * `getPlatformPaths()` reads fresh on every call: env-paths is microsecond-fast
+ * and a process-wide cache would mask XDG / APPDATA env-var changes that test
+ * code legitimately makes. `getSystemInfo()` IS cached because hostname /
+ * platform / arch don't change during a process lifetime.
+ *
+ * @packageDocumentation
+ * @task T1883
+ */
+import { arch, homedir, hostname, platform, release } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import envPaths from 'env-paths';
+/**
+ * Normalize a home-override env var value to an absolute path.
+ *
+ * Returns `undefined` for absent / blank values so callers fall back to the
+ * env-paths default. Accepts `~`, `~/foo`, absolute paths, and relative paths
+ * (which are resolved against `homedir()`).
+ *
+ * @internal
+ */
+function resolveHomeOverride(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === '~')
+        return homedir();
+    if (trimmed.startsWith('~/'))
+        return join(homedir(), trimmed.slice(2));
+    if (isAbsolute(trimmed))
+        return resolve(trimmed);
+    return resolve(homedir(), trimmed);
+}
+/**
+ * Create a platform-paths resolver bound to a specific app name and home env var.
+ *
+ * Returns a resolver with its own internal `SystemInfo` cache. Path reads are
+ * always fresh (env-paths is fast); only system info is cached.
+ *
+ * @param appName - The application name passed to `env-paths` (e.g. `"cleo"`,
+ *   `"agents"`).
+ * @param homeEnvVar - The env var name that overrides the data directory
+ *   (e.g. `"CLEO_HOME"`, `"AGENTS_HOME"`). Tilde-prefixed and relative
+ *   values are resolved against `homedir()`.
+ *
+ * @example
+ * ```typescript
+ * const cleo = createPlatformPathsResolver('cleo', 'CLEO_HOME');
+ * cleo.getPlatformPaths().data; // → "/home/user/.local/share/cleo"  (Linux, no override)
+ * ```
+ *
+ * @public
+ */
+export function createPlatformPathsResolver(appName, homeEnvVar) {
+    let cachedSysInfo = null;
+    function readPlatformPaths() {
+        const ep = envPaths(appName, { suffix: '' });
+        const override = resolveHomeOverride(process.env[homeEnvVar]);
+        return {
+            data: override ?? ep.data,
+            config: ep.config,
+            cache: ep.cache,
+            log: ep.log,
+            temp: ep.temp,
+        };
+    }
+    return {
+        getPlatformPaths: readPlatformPaths,
+        getSystemInfo() {
+            if (cachedSysInfo)
+                return cachedSysInfo;
+            cachedSysInfo = {
+                platform: platform(),
+                arch: arch(),
+                release: release(),
+                hostname: hostname(),
+                nodeVersion: process.version,
+                paths: readPlatformPaths(),
+            };
+            return cachedSysInfo;
+        },
+        resetCache() {
+            cachedSysInfo = null;
+        },
+    };
+}
+//# sourceMappingURL=platform-paths.js.map

package/dist/platform-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-paths.js","sourceRoot":"","sources":["../src/platform-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,WAAW,CAAC;AAiFjC;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,KAAyB;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACtC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,UAAkB;IAElB,IAAI,aAAa,GAAsB,IAAI,CAAC;IAE5C,SAAS,iBAAiB;QACxB,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAC9D,OAAO;YACL,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC,IAAI;YACzB,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,GAAG,EAAE,EAAE,CAAC,GAAG;YACX,IAAI,EAAE,EAAE,CAAC,IAAI;SACd,CAAC;IACJ,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,iBAAiB;QACnC,aAAa;YACX,IAAI,aAAa;gBAAE,OAAO,aAAa,CAAC;YACxC,aAAa,GAAG;gBACd,QAAQ,EAAE,QAAQ,EAAE;gBACpB,IAAI,EAAE,IAAI,EAAE;gBACZ,OAAO,EAAE,OAAO,EAAE;gBAClB,QAAQ,EAAE,QAAQ,EAAE;gBACpB,WAAW,EAAE,OAAO,CAAC,OAAO;gBAC5B,KAAK,EAAE,iBAAiB,EAAE;aAC3B,CAAC;YACF,OAAO,aAAa,CAAC;QACvB,CAAC;QACD,UAAU;YACR,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/worktree-paths.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Worktree path primitives — project hashing + canonical worktree root.
+ *
+ * Canonical layout per D029:
+ *   `<cleoHome>/worktrees/<projectHash>/<taskId>/`
+ *
+ * `cleoHome` is resolved via {@link getCleoHome} (env-paths + `CLEO_HOME` override).
+ *
+ * @task T1883
+ */
+/**
+ * Compute a stable 16-character project hash from an absolute project root path.
+ *
+ * Uses SHA-256 truncated to 16 hex chars. The truncation is consistent with
+ * the historical implementation in `branch-lock.ts#resolveAgentWorktreeRoot`
+ * (the root cause of the duplicated logic this package consolidates).
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns 16-character lowercase hex string.
+ *
+ * @public
+ */
+export declare function computeProjectHash(projectRoot: string): string;
+/**
+ * Resolve the worktrees root directory for a given project hash.
+ *
+ * Result: `<cleoHome>/worktrees/<projectHash>/`
+ *
+ * Priority:
+ *   1. Explicit `worktreeRoot` arg (used by tests / config overrides)
+ *   2. `CLEO_HOME` env var via {@link getCleoHome}
+ *   3. env-paths XDG data dir via {@link getCleoHome}
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param worktreeRoot - Optional explicit override for the full root path.
+ * @returns Absolute path to the project-scoped worktree root directory.
+ *
+ * @public
+ */
+export declare function resolveWorktreeRootForHash(projectHash: string, worktreeRoot?: string): string;
+/**
+ * Resolve the worktree directory for a specific task.
+ *
+ * Result: `<cleoHome>/worktrees/<projectHash>/<taskId>/`
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param taskId - The task ID.
+ * @param worktreeRoot - Optional override for the worktree root.
+ * @returns Absolute path to the task-specific worktree directory.
+ *
+ * @public
+ */
+export declare function resolveTaskWorktreePath(projectHash: string, taskId: string, worktreeRoot?: string): string;
+/**
+ * Resolve the canonical worktrees-by-project root for the current process —
+ * `<cleoHome>/worktrees/`. Project-agnostic; useful when listing or scanning
+ * across all projects.
+ *
+ * @returns Absolute path to `<cleoHome>/worktrees/`.
+ *
+ * @public
+ */
+export declare function getCleoWorktreesRoot(): string;
+//# sourceMappingURL=worktree-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-paths.d.ts","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/worktree-paths.js

@@ -0,0 +1,79 @@
+/**
+ * Worktree path primitives — project hashing + canonical worktree root.
+ *
+ * Canonical layout per D029:
+ *   `<cleoHome>/worktrees/<projectHash>/<taskId>/`
+ *
+ * `cleoHome` is resolved via {@link getCleoHome} (env-paths + `CLEO_HOME` override).
+ *
+ * @task T1883
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { getCleoHome } from './cleo-paths.js';
+const WORKTREES_SUBDIR = 'worktrees';
+const PROJECT_HASH_LENGTH = 16;
+/**
+ * Compute a stable 16-character project hash from an absolute project root path.
+ *
+ * Uses SHA-256 truncated to 16 hex chars. The truncation is consistent with
+ * the historical implementation in `branch-lock.ts#resolveAgentWorktreeRoot`
+ * (the root cause of the duplicated logic this package consolidates).
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns 16-character lowercase hex string.
+ *
+ * @public
+ */
+export function computeProjectHash(projectRoot) {
+    return createHash('sha256').update(projectRoot).digest('hex').slice(0, PROJECT_HASH_LENGTH);
+}
+/**
+ * Resolve the worktrees root directory for a given project hash.
+ *
+ * Result: `<cleoHome>/worktrees/<projectHash>/`
+ *
+ * Priority:
+ *   1. Explicit `worktreeRoot` arg (used by tests / config overrides)
+ *   2. `CLEO_HOME` env var via {@link getCleoHome}
+ *   3. env-paths XDG data dir via {@link getCleoHome}
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param worktreeRoot - Optional explicit override for the full root path.
+ * @returns Absolute path to the project-scoped worktree root directory.
+ *
+ * @public
+ */
+export function resolveWorktreeRootForHash(projectHash, worktreeRoot) {
+    if (worktreeRoot)
+        return worktreeRoot;
+    return join(getCleoHome(), WORKTREES_SUBDIR, projectHash);
+}
+/**
+ * Resolve the worktree directory for a specific task.
+ *
+ * Result: `<cleoHome>/worktrees/<projectHash>/<taskId>/`
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param taskId - The task ID.
+ * @param worktreeRoot - Optional override for the worktree root.
+ * @returns Absolute path to the task-specific worktree directory.
+ *
+ * @public
+ */
+export function resolveTaskWorktreePath(projectHash, taskId, worktreeRoot) {
+    return join(resolveWorktreeRootForHash(projectHash, worktreeRoot), taskId);
+}
+/**
+ * Resolve the canonical worktrees-by-project root for the current process —
+ * `<cleoHome>/worktrees/`. Project-agnostic; useful when listing or scanning
+ * across all projects.
+ *
+ * @returns Absolute path to `<cleoHome>/worktrees/`.
+ *
+ * @public
+ */
+export function getCleoWorktreesRoot() {
+    return join(getCleoHome(), WORKTREES_SUBDIR);
+}
+//# sourceMappingURL=worktree-paths.js.map

package/dist/worktree-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-paths.js","sourceRoot":"","sources":["../src/worktree-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,gBAAgB,GAAG,WAAW,CAAC;AACrC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB,EAAE,YAAqB;IACnF,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,MAAc,EACd,YAAqB;IAErB,OAAO,IAAI,CAAC,0BAA0B,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cleocode/paths",
+  "version": "2026.5.26",
+  "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.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "keywords": [
+    "cleo",
+    "paths",
+    "xdg",
+    "env-paths",
+    "platform"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "author": "CLEO Code <hello@cleocode.dev>",
+  "license": "MIT",
+  "dependencies": {
+    "env-paths": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kryptobaseddev/cleo.git",
+    "directory": "packages/paths"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}