Skip to content

fix(brain): align Windows getCleoHome with env-paths Data subdir#103

Open
calabresejordan-Caljord wants to merge 2 commits intokryptobaseddev:mainfrom
calabresejordan-Caljord:fix/brain-windows-cleo-home-env-paths-alignment
Open

fix(brain): align Windows getCleoHome with env-paths Data subdir#103
calabresejordan-Caljord wants to merge 2 commits intokryptobaseddev:mainfrom
calabresejordan-Caljord:fix/brain-windows-cleo-home-env-paths-alignment

Conversation

@calabresejordan-Caljord
Copy link
Copy Markdown

Target branch

  • develop -- Normal feature/fix (default)
  • main -- Hotfix only (bypasses develop, requires back-merge to develop after)

Note on target: I'd normally target develop per the PR template, but develop and main have no common ancestor (gh api repos/kryptobaseddev/cleo/compare/develop...main returns "No common ancestor"). develop is from 2026-03-08 and contains only packages/ct-agents and packages/ct-skills -- the Brain package extraction (commit 725fc423, T969) doesn't exist on that branch. Targeting main as a hotfix per the template's exception. Happy to retarget if there's a different active branch I should use.

Process compliance

  • I did not push directly to a protected branch
  • This PR comes from a fix/... branch
  • Commit messages use <type>(<scope>): <subject> (no T-id since this is an external bug; scope is the package)
  • No tag/release work in this PR

Summary

  • Fix getCleoHome() on Windows in both @cleocode/brain and @cleocode/studio to append the Data subdir, matching the env-paths convention the CLI uses.
  • Correct docs/specs/DATABASE-ARCHITECTURE.md Windows path to match.
  • One bug, three files, two commits.

Change type

  • Bug fix (non-breaking change that fixes an issue)
  • Documentation update

Related issues

Closes #102

Repro (before this PR)

Verified on this Windows host (cleo@2026.4.158, @cleocode/brain@2026.4.161, Node v24.13.0, Win 11):

cleo admin paths --json
# data.cleoHome = C:\Users\<user>\AppData\Local\cleo\Data    (correct: env-paths convention)

node --input-type=module -e "import('@cleocode/brain').then(m => console.log(m.getCleoHome()))"
# C:\Users\<user>\AppData\Local\cleo                          (wrong: missing 'Data')

ls "C:\Users\<user>\AppData\Local\cleo\nexus.db"             # NOT FOUND
ls "C:\Users\<user>\AppData\Local\cleo\Data\nexus.db"        # found, 256 KB

Result: getNexusSubstrate() / getSignaldockSubstrate() silently return 0 nodes despite populated DBs.

After this PR

node --input-type=module -e "import('@cleocode/brain').then(m => console.log(m.getCleoHome()))"
# C:\Users\<user>\AppData\Local\cleo\Data                    (matches CLI)

How was this tested

  • Ran pnpm test (Vitest) -- not run; this is a Windows-host-only path resolution change with no existing tests for cleo-home.ts (no __tests__/cleo-home.test.ts in the brain package). Happy to add a test if you want one written.
  • Ran pnpm typecheck -- not run locally
  • Ran pnpm build -- not run locally
  • Tested manually on Windows. Verified that with the patched dist/src/cleo-home.js applied to a global install, getCleoHome() returns %LOCALAPPDATA%\cleo\Data and Brain's nexus/signaldock paths now resolve to existing files (exists: true). Project-tier substrates (tasks/brain/conduit) continue to work unchanged.

CLEO-specific checklist

  • Atomic operations: N/A (no writes)
  • Validation: N/A (no schema-bearing code)
  • Error handling: N/A (pure path resolution)
  • No time estimates: confirmed
  • Commit messages: fix(brain): ... and docs(database-architecture): ... per CONTRIBUTING.md (T-id omitted because non-release; release-lint hook exits 0 for non-release commits per scripts/hooks/commit-msg-release-lint.mjs)
  • Verb standards: N/A (no new commands)

Environment

CLEO version: 2026.4.158 (CLI), 2026.4.161 (@cleocode/brain)
Node version: v24.13.0
OS: Windows 11 Pro 10.0.26200

AI agent disclosure

  • This PR was written entirely by a human
  • This PR was written with AI agent assistance (human reviewed)
  • This PR was written primarily by an AI agent (human supervised)

Notes

Both commits include Signed-off-by: Jordan Calabrese <calabresejordan@gmail.com>.

packages/brain/src/cleo-home.ts notes in its header that it is "a trimmed mirror of packages/studio/src/lib/server/cleo-home.ts ... Kept in sync manually" -- both files are patched together so they stay in sync. Suggest a follow-up to either factor getCleoHome into a shared utility (perhaps in packages/contracts) or replace both with a direct dependency on env-paths, but that's out of scope here.

On Windows, both `@cleocode/brain` and `@cleocode/studio` resolved
`cleoHome` to `%LOCALAPPDATA%\cleo`, but the CLI uses `env-paths`
(or equivalent) which appends a `Data` subdir, so `cleo admin paths
--json` reports `cleoHome` as `%LOCALAPPDATA%\cleo\Data`.

Result: Brain's `getNexusDbPath()` and `getSignaldockDbPath()` pointed
at non-existent files. `getNexusSubstrate()` / `getSignaldockSubstrate()`
silently returned 0 nodes despite populated DBs being present at the
correct (one-level-deeper) path. Setting `CLEO_HOME=%LOCALAPPDATA%\cleo\Data`
worked around it.

Patch the win32 branch in both files to append `'Data'`, with a comment
explaining the env-paths convention. macOS and Linux branches are
unchanged. The `packages/brain/src/cleo-home.ts` header comment is
updated to match.

The Brain header notes that this file is "a trimmed mirror of
packages/studio/src/lib/server/cleo-home.ts ... Kept in sync manually"
so both files must be patched together.

Signed-off-by: Jordan Calabrese <calabresejordan@gmail.com>
The spec listed the Windows nexus.db location as `%APPDATA%/cleo/`
(Roaming, no `Data` subdir), but the CLI actually writes to
`%LOCALAPPDATA%/cleo/Data/`. The previous text mismatched both:

  1. wrong base env var (`%APPDATA%` is Roaming; CLEO uses Local).
  2. missing the `Data` subdir that the env-paths convention appends.

Update the location line for nexus.db so it matches `cleo admin
paths --json` and the corrected Brain/Studio code paths in the
companion fix.

Signed-off-by: Jordan Calabrese <calabresejordan@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Brain Windows getCleoHome() returns wrong path (missing env-paths Data subdir)

1 participant