squad_state_list fails for root on adapter-backed backends: StateBackendStorageAdapter.toRelative() returns "." for squadDir

Open
#2,231 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
63/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
backend, cli

Research direction

Start in packages/squad-sdk/src/state-backend.ts and inspect StateBackendStorageAdapter.toRelative() alongside its list and directory methods. Then read packages/squad-sdk/src/tools/index.ts for normalizeStateToolDir() and the existing key validation. Add regression coverage for root listing while preserving traversal and file-operation rejection; done means the listed root entries are returned and the specified invalid paths still fail.

Written by the indexing model from the issue text.

Description

wave:1-next wave1:P1

Summary

squad_state_list with dir omitted (or "", or ".squad") fails on any backend routed through StateBackendStorageAdapter (observed with stateBackend: "two-layer"):

Failed to list state: State key must not contain . or .. path segments

squad_state_list {dir: "decisions"} works.

Environment

  • squad CLI v1.0.1 (WinGet bradygaster.Squad), Windows
  • .squad/config.json → stateBackend: "two-layer"; squad_state_health → State backend storage: StateBackendStorageAdapter
  • Source references below are from main @ 89d6302576ce03b87fe0519235854c9e8638737f (bug still present)

Minimal repro

  1. Repo with stateBackend: "two-layer" (or orphan / git-notes).
  2. Run squad state-mcp, call squad_state_list {}.
  3. Observe the error above.

Unit-level repro:

const adapter = new StateBackendStorageAdapter(new OrphanBranchBackend(repo), squadDir);
adapter.listSync(squadDir); // throws: State key must not contain . or .. path segments

Root cause

  1. packages/squad-sdk/src/tools/index.ts normalizeStateToolDir() correctly maps an omitted dir to "", then calls this.storage.listSync(path.join(this.squadRoot, "")), i.e. listSync(squadRoot).
  2. packages/squad-sdk/src/state-backend.ts StateBackendStorageAdapter.toRelative() has:
    if (fileCmp === squadCmp) {
      return '.';
    }
    
  3. Every backend list() runs normalizeKey(relativeDir). normalizeKey explicitly allows "" as root ("Empty string after normalization means root — valid for list() operations"), but "." is non-empty, so validateStateKey('.') throws.

The adapter emits a root sentinel the backends do not accept.

Suggested fix (keeps traversal rejection)

Do not relax validateStateKey. Map squadDir to "" only for list-shaped reads:

  • list / listSync / isDirectory / isDirectorySync: when the path resolves to squadDir, pass "".
  • Keep "." (and therefore rejection) for file operations and especially deleteDir/deleteDirSync. Returning "" there would turn deleteDir(squadDir) into a wipe of all state, and read("") on git backends could resolve to a tree object.

For example, add private toRelativeDir(p) { const r = this.toRelative(p); return r === '.' ? '' : r; } and use it in the four list methods.

Regression tests

  • adapter.listSync(squadDir) returns root entries for the orphan, git-notes, and two-layer backends.
  • squad_state_list {} and {dir: ""} succeed.
  • {dir: ".."}, {dir: "a/../b"}, and {dir: "."} still fail with the . or .. error.
  • adapter.deleteDirSync(squadDir) and adapter.readSync(squadDir) still throw.

Downstream report: OlyForge3D/PrintFarmer#3372

Dominant language
TypeScript
Stars
3.4k
Forks
516
Avg merge
1d 15h
Merged PRs (30d)
116

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/squad

All issues in github/squad

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.