Circular extends detected in config.json on Windows blocks all commands

[DravenYe]

Environment

• OS: Windows 11
• poe-code version: 3.0.198 (global install)
• Node.js: (run node -v to check)

Description

On Windows, every command (login, configure, wrap, etc.) fails with a Circular extends detected error referencing
~/.poe-code/config.json visiting itself twice. The error occurs even when config.json is empty ({}) or deleted entirely — the tool
recreates and immediately detects a circular reference in it.

Steps to Reproduce

1. Install poe-code globally on Windows: npm install -g poe-code
2. Run any command, e.g. poe-code login or poe-code configure

Error Output

■ Error: Circular extends detected.
│ Visited files:
│ - C:\Users<user>.poe-code\config.json
│ - C:\Users<user>.poe-code\config.json

Root Cause (identified)

In resolveBaseChain (packages/config-extends/src/resolve.ts), when the discovered base file path is already in the visited set, the
code unconditionally throws — even when optional is true (i.e. no explicit extends field in the document). The fix is to respect the
optional flag:

if (visited.has(discoveredBase.filePath)) {

• if (optional) return void 0;
  throw new Error(
  Circular extends detected.\nVisited files:\n- ${[...visited, discoveredBase.filePath].join("\n- ")}
  );
  }

This one-line fix resolves the issue on Windows.

Workaround

Manually apply the above patch to the installed dist/index.js.

[kamilio]

@poe-code-agent confirm and resolve

[poe-code-agent]

Confirmed and resolved in #275.

I opened a PR that treats optional auto-extend self-discovery as no base found, while keeping explicit circular extends errors intact. Added a regression test for the self-discovery case.

Verification passed:

• npm run test:unit -- packages/config-extends/src/resolve.test.ts
• npm run lint:types
• npx eslint packages/config-extends/src/resolve.ts packages/config-extends/src/resolve.test.ts
• npm run build
• npm run test

[DravenYe]

Additional reproduction on macOS/Linux: triggered when cwd == $HOME

I ran into the same error on macOS (poe-code 3.0.198), but the root cause is a different code path. Documenting it here since the symptom is identical.

Reproduction

Run any poe-code command from the home directory:

cd ~
npx poe-code@latest login

→ AuthenticationError: Circular extends detected.

Visited files:

- /Users//.poe-code/config.json

- /Users//.poe-code/config.json

Root cause

The problem is in readMergedDocument (packages/poe-code-config/src/store.ts):

async function readMergedDocument(fs, globalPath, projectPath) {
const globalDocument = await readStoredDocument(fs, globalPath);
if (!projectPath) { // ← only guards against null
return globalDocument.data;
}
// passes both paths into resolve() for extends-chain resolution...
}

The two paths are computed as:

const configPath = path.join(homeDir, ".poe-code", "config.json");
const projectConfigPath = path.join(cwd, ".poe-code", "config.json");

When cwd === homeDir (running from ~), both resolve to the same file. resolve() adds the file to visited, then autoExtend: true causes it to look up a base
in the same directory — which finds the same file again — triggering the circular check.

Fix

One-line guard in readMergedDocument:

if (!projectPath || projectPath === globalPath) {
return globalDocument.data;
}

Workaround (until patched)

Add a shell function to ~/.zshrc / ~/.bashrc so poe-code always runs from /tmp:

poe-code() { (cd /tmp && npx poe-code@latest "$@") }

---

Note: this is separate from the Windows issue described above, which involves resolveBaseChain not respecting the optional flag. Both bugs produce the same
error message but require independent fixes.

[kamilio]

@poe-code-agent redo with these repro cases

[poe-code-agent]

Updated #275 with the new repro cases.

Added the second fix for cwd == $HOME: readMergedDocument now returns the global config directly when the project config path is the same file, so it does not try to resolve the global config as its own project base.

Verification passed:

• npm run test:unit -- packages/poe-code-config/src/poe-code-config.test.ts packages/config-extends/src/resolve.test.ts
• npx eslint packages/poe-code-config/src/store.ts packages/poe-code-config/src/poe-code-config.test.ts packages/config-extends/src/resolve.ts packages/config-extends/src/resolve.test.ts
• npm run lint:types
• npm run test (pre-push)