feat: add project-navigation commands (open, pick, list, add) by barichter · Pull Request #1392 · bradygaster/squad

barichter · 2026-06-25T22:16:30Z

Depends on #1391. Until that PR merges, this PR's diff also includes its single commit (b186993). Both target dev; no retarget needed after PR1 merges.

What

PR1 added a global registry of every project where squad init runs, plus a
read-only squad projects list. This PR makes that registry actionable. It adds
four navigation commands so you can jump to, choose, alias-list, and register
your Squad projects without leaving the terminal.

squad open [name]

Resolves a registered project and launches Copilot in that project's directory.

squad open <name>: looks up the project by name, partial name, or path, then
starts copilot in that directory.
squad open with no name, on a TTY, shows a numbered picker.
squad open with no name, when stdout is not a TTY, prints the project list
and a hint to pass a name, rather than blocking on a prompt.
squad open <name> --print-path (-p) prints the resolved path instead of
launching, for shell integrations like cd (squad open foo -p).

squad pick

An always-interactive opener. It presents the numbered picker of all registered
projects, prompts for a choice, then opens the chosen project in Copilot. It is
equivalent to running squad open after manually finding a name in the list.
Positional arguments are stripped so it always enters the picker; flags such as
--print-path are forwarded.

squad list

A convenience alias for squad projects. It accepts the same flags, including
--open, and behaves identically. Existing squad projects usage is unchanged.

squad add [path]

Registers a pre-existing directory in the global registry so it shows up in
squad projects, squad list, and squad pick, without re-running
squad init and without scaffolding a .squad/ directory.

squad add <path>: registers the directory at that path. With no path, it
registers the current directory.
squad add <path> --name <name>: sets a custom display name. Without it, the
directory basename is used.
Paths with spaces are handled even when passed unquoted: the remaining
argument tokens are rejoined into the full path. If the reconstructed path does
not exist and there were multiple tokens, it prints a hint to quote the path.

Why

A list of projects is only useful if you can act on it. These commands close the
loop: from "what have I initialized?" to "take me there," to "let me choose from
a menu," to "remember this directory too." squad open is the core verb,
squad pick is the discoverable interactive form, squad list is muscle-memory
ergonomics, and squad add lets you backfill projects that predate the registry
or that you set up by hand.

How

SDK resolver: resolveProject(query) in projects-registry.ts. Resolution
order, first match wins:

Exact name match (case-insensitive on win32 and darwin). One hit returns
{ match }; several with the same name return { ambiguous }.
Exact path match via samePath on the resolved absolute paths.
Unique case-insensitive substring match on name. One hit returns { match },
several return { ambiguous }.

It returns a discriminated union: { match }, { ambiguous: [...] }, or
{ notFound: true }. An empty query (after trimming) always returns
{ notFound: true }.

SDK registration: registerProject(name, path) (introduced in PR1, reused
here by squad add). It is idempotent: re-registering a path that already exists
updates that entry in place and preserves the original created_at, rather than
adding a duplicate. squad add first checks whether the path is already present
so it can report "Added" versus "Updated" accurately.

Command implementations:

open.ts owns all shared opener logic: the resolver call, the empty-registry
and not-found and ambiguous messages, the numbered picker, the non-TTY list
fallback, the missing-on-disk guard, --print-path, and the Copilot launch.
Launch is platform-aware (shell: true on win32) and inherits stdio. If
copilot is not on PATH (ENOENT), it prints the path with a hint instead of
crashing.
pick.ts delegates to runOpen with positional args removed, so all picker
and launch behavior is reused with no duplication.
projects.ts gains an --open/-o branch that delegates to runOpen;
listing remains the default.
add.ts parses --name, rejoins remaining tokens into a path, resolves it to
absolute, validates it exists and is a directory, then calls registerProject.

cli-entry.ts wires open, pick, and add to their handlers and routes both
projects and list to runProjects. command-help.ts adds dedicated help
blocks for open, pick, and add, updates the projects help to document
--open, and registers list as an alias of projects.

Scope and safety

squad open, squad pick, and squad list are read-only against the
registry. They never write.
squad add DOES write to the registry: it calls registerProject, which adds
or updates a single entry in projects.json. It does not scaffold .squad/,
does not touch project contents, and does not change how squad init behaves.
Re-adding an existing path updates in place and preserves created_at.
No change to PR1's behavior or to any project's .squad/ state.
Every command degrades gracefully on edge cases: empty registry, no match,
ambiguous match, non-TTY invocation, missing-on-disk path, copilot not
installed, nonexistent or non-directory add target, and spaced unquoted
paths.

Tests / build

npm run build clean (tsc, both packages).
Lint clean (tsc --noEmit on both package tsconfigs).
Targeted suites green, 21 tests passing:
- test/cli/add.test.ts (4): registers and shows up in squad list, clear
  error for a nonexistent path, spaced-path reconstruction from split argv
  tokens, and the quoting hint for a nonexistent multi-token path. All assert
  no stack trace leaks.
- test/cli/command-help.test.ts (14): the command-help end-to-end suite,
  covering the help blocks and the command list now including the new verbs.
- test/global-squad-isolation.test.ts (3): proves the new test harness
  redirects the global Squad path to an OS temp dir.
New test-isolation infrastructure: test/setup/isolate-global-squad.ts
redirects resolveGlobalSquadPath() to a per-worker temp dir (via APPDATA,
LOCALAPPDATA, XDG_CONFIG_HOME, and HOME), wired through vitest.config.ts
as a setup file. Because PR1 made squad init write to the global
projects.json, this prevents the test suite from polluting a developer's real
registry.

Files (17 changed, +590/-4)

.changeset/squad-add-command.md
.changeset/squad-list-alias.md
.changeset/squad-open-command.md
.changeset/squad-pick-command.md
packages/squad-cli/src/cli-entry.ts
packages/squad-cli/src/cli/commands/add.ts
packages/squad-cli/src/cli/commands/open.ts
packages/squad-cli/src/cli/commands/pick.ts
packages/squad-cli/src/cli/commands/projects.ts
packages/squad-cli/src/cli/core/command-help.ts
packages/squad-sdk/src/index.ts
packages/squad-sdk/src/projects-registry.ts
test/cli/add.test.ts
test/cli/command-help.test.ts
test/global-squad-isolation.test.ts
test/setup/isolate-global-squad.ts
vitest.config.ts

Changeset

Four changeset files, all minor:

squad-open-command.md: @bradygaster/squad-cli minor, @bradygaster/squad-sdk minor.
squad-pick-command.md: @bradygaster/squad-cli minor.
squad-list-alias.md: @bradygaster/squad-cli minor.
squad-add-command.md: @bradygaster/squad-cli minor.

The SDK bump rides on the open/resolver changeset since resolveProject is a new
public SDK export; the other three are CLI-only.

Every repo-level 'squad init' now records the project (name, path, created_at) in a global projects.json under Squad's existing global home, and a new 'squad projects' command lists them newest-first. The write is additive, idempotent on path, and wrapped in try/catch so a registry failure never blocks init. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>