Repository navigation
feat(release): parameterize npm distribution identity (rename off @bradygaster, scope TBD) - #2536
tamirdresher wants to merge 4 commits into
Conversation
…squad/cli + @squad/sdk Move Squad's npm packages off the @bradygaster scope behind a single identity file (scripts/release/distribution-identity.json) and a re-runnable codemod (scripts/rename-distribution-identity.mjs). Existing installs keep working: the CLI recognizes legacy @bradygaster names in MCP entries and agent stamps, and `squad upgrade --self` uninstalls the legacy package before installing the new one. The release policy gate derives its verified tarball names from the identity file. Homebrew tap and WinGet ID are unchanged. Nothing is published, deprecated, or dispatched. Do not merge until npm scope ownership is confirmed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
| `squad-insider` Homebrew casks, or as `bradygaster.Squad.Preview` and | ||
| `bradygaster.Squad.Insider` WinGet packages. | ||
|
|
||
| > **Upgrading from `@bradygaster/squad-cli`?** The npm packages are now | ||
| > `@squad/cli` and `@squad/sdk`. Run `npm uninstall -g @bradygaster/squad-cli` | ||
| > before installing `@squad/cli`; see the | ||
| > [Package Rename guide](https://github.github.com/squad/docs/get-started/package-rename/). |
| mcpServers: | ||
| squad_state: | ||
| command: npx | ||
| args: ["-y", "@bradygaster/squad-cli@latest", "state-mcp"] | ||
| args: ["-y", "@squad/cli@latest", "state-mcp"] |
| - Slash commands: `/squad:ralph`, `/squad:cast`, `/squad:ceremony`, `/squad:status`, `/squad:dashboard`. | ||
| - Squad's advisory governance hooks. They act only when `.squad/config.json` has `"claudeHooks": "advisory"`. | ||
| - `squad` on the Bash PATH. The launcher runs, in order: `SQUAD_CLI`, the project's `node_modules/@bradygaster/squad-cli`, or a `squad` on PATH. With none of them it fails and says how to install the CLI; set `SQUAD_ALLOW_NPX=1` to let it run `npx -y @bradygaster/squad-cli@2.0.0` instead. | ||
| - `squad` on the Bash PATH. The launcher runs, in order: `SQUAD_CLI`, the project's `node_modules/@squad/cli`, or a `squad` on PATH. With none of them it fails and says how to install the CLI; set `SQUAD_ALLOW_NPX=1` to let it run `npx -y @squad/cli@2.0.0` instead. |
🔴 Impact Analysis — PR #2536Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (8 files)
copilot-config (4 files)
docs (60 files)
root (63 files)
scripts (26 files)
squad-cli (88 files)
squad-sdk (20 files)
squad-state (1 file)
templates (8 files)
tests (194 files)
|
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 commits — consider squashing before review |
| ❌ | Not in draft | PR is still in draft — mark as ready for review when done |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 1 check(s) failing: CodeQL |
Files Changed (472 files, +2376 −1881)
| File | +/− |
|---|---|
.changeset/rename-npm-packages-squad-scope.md |
+6 −0 |
.copilot/skills/architectural-review/SKILL.md |
+4 −4 |
.copilot/skills/pr-lifecycle/SKILL.md |
+2 −2 |
.copilot/skills/protected-files/SKILL.md |
+1 −1 |
.copilot/skills/release-process/SKILL.md |
+5 −5 |
.github/actions/squad-init/action.yml |
+1 −1 |
.github/workflows/squad-ci.yml |
+1 −1 |
.github/workflows/squad-insider-publish.yml |
+6 −6 |
.github/workflows/squad-npm-publish.yml |
+12 −12 |
.github/workflows/squad-promote.yml |
+4 −4 |
.github/workflows/squad-release-verify.yml |
+2 −2 |
.github/workflows/squad-release.yml |
+1 −1 |
.github/workflows/squad-upgrade-matrix.yml |
+1 −1 |
.squad-templates/model-selection-reference.md |
+1 −1 |
.squad-templates/ralph-reference.md |
+8 −8 |
.squad-templates/session-init-reference.md |
+1 −1 |
.squad-templates/skills/e2e-template-testing/SKILL.md |
+3 −3 |
.squad-templates/skills/release-process/SKILL.md |
+7 −7 |
.squad-templates/skills/squad-version-check/SKILL.md |
+7 −7 |
.squad-templates/skills/versioning-policy/SKILL.md |
+4 −4 |
.squad-templates/workflows/squad-insider-release.yml |
+1 −1 |
.squad/templates/ralph-reference.md |
+8 −8 |
CONTRIBUTING.md |
+7 −7 |
CONTRIBUTORS.md |
+1 −1 |
Dockerfile |
+1 −1 |
README.md |
+11 −6 |
README.zh.md |
+10 −6 |
cli.js |
+2 −2 |
docs/SQUAD-2.0-OVERVIEW.md |
+6 −6 |
docs/migration/teams-async-adapter.md |
+2 −2 |
docs/proposals/squad-2.0-security-and-isolation.md |
+1 −1 |
docs/specification/README.md |
+1 −1 |
docs/specification/adr-002-work-claims-and-external-queues.md |
+1 −1 |
docs/specification/client-backend-decoupling-v0.2.md |
+2 −2 |
docs/specification/client-harness-adapters-v0.2.md |
+6 −6 |
docs/src/components/Footer.astro |
+2 −2 |
docs/src/content/docs/concepts/squad-2-0-architecture.md |
+10 −10 |
docs/src/content/docs/features/built-in-roles.md |
+1 −1 |
docs/src/content/docs/features/claude-code-plugin.md |
+3 −3 |
docs/src/content/docs/features/coordinator-as-agent-export.md |
+2 −2 |
docs/src/content/docs/features/cost-tracking.md |
+1 −1 |
docs/src/content/docs/features/dual-mode-deployment.md |
+2 −2 |
docs/src/content/docs/features/mcp-frontmatter.md |
+2 −2 |
docs/src/content/docs/features/scratch-dir.md |
+3 −3 |
docs/src/content/docs/features/security-hardening.md |
+1 −1 |
docs/src/content/docs/features/self-upgrade.md |
+2 −2 |
docs/src/content/docs/features/standalone-install.md |
+1 −1 |
docs/src/content/docs/features/state-backends.md |
+3 −3 |
docs/src/content/docs/features/storage-provider.md |
+2 −2 |
docs/src/content/docs/features/teams-comms.md |
+2 −2 |
| ... | +422 more files |
Total: +2376 −1881
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
🏗️ Architectural Review
Automated architectural review — informational only. |
…ntity Pinned npm producers (0.9.1, 0.13.1, 1.0.0) were published as @bradygaster/squad-cli and @bradygaster/squad-sdk, so the suite now picks whichever known current/legacy identity the fixture pins, and packs the tree under test under the current names. The renderer reads the same file, so a later scope retarget leaves the harness unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Both platforms re-recorded by run 44384646543 at the identity-aware harness (48482391aaaf): 35 pass, 7 structurally inapplicable, 0 fail per OS. Folded with render-upgrade-matrix.mjs --merge; only runs data and the generated docs section change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
| "@squad/cli": major | ||
| "@squad/sdk": major | ||
| --- | ||
|
|
||
| Rename the npm packages from `@bradygaster/squad-cli` and `@bradygaster/squad-sdk` to `@squad/cli` and `@squad/sdk`. `squad upgrade --self` and the update banner detect a legacy global install and remove it before installing the new package, and MCP config entries that use the old package name are still recognized as Squad-managed. Distribution names now come from `scripts/release/distribution-identity.json`, and `scripts/rename-distribution-identity.mjs` rewrites the repository when they change. |
| | Method | Command | | ||
| |--------|---------| | ||
| | npm (all platforms, Node.js 22.5+) | `npm install -g @bradygaster/squad-cli` | | ||
| | npm (all platforms, Node.js 22.5+) | `npm install -g @squad/cli` | |
…L findings in distribution rename Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
| npx @squad/cli watch # polls every 10 minutes (default) | ||
| npx @squad/cli watch --interval 5 # polls every 5 minutes | ||
| npx @squad/cli watch --interval 30 # polls every 30 minutes |
| "squad_state": { | ||
| "command": "npx", | ||
| "args": ["-y", "@bradygaster/squad-cli@latest", "state-mcp"], | ||
| "args": ["-y", "@squad/cli@latest", "state-mcp"], |
| ```bash | ||
| npm uninstall -g @bradygaster/squad-cli | ||
| npm install -g @squad/cli | ||
| ``` | ||
|
|
||
| With pnpm or yarn: | ||
|
|
||
| ```bash | ||
| pnpm remove -g @bradygaster/squad-cli && pnpm add -g @squad/cli | ||
| yarn global remove @bradygaster/squad-cli && yarn global add @squad/cli | ||
| ``` | ||
|
|
||
| Once you're running a build that knows about the rename, `squad upgrade --self` does this for you: it detects an install made under the old name and runs the uninstall before installing `@squad/cli`. Use `squad upgrade --self --dry-run` to see the exact command first. |
Warning
Draft, do not merge. The target npm scope is not settled.
@squadon npm is not owned by this team (Brady: "if you mean there's a team at npm/squad - that's not me"), and on 2026-11-18 Brady chose to ship 2.0.0 under the existing@bradygasternames and rename later ("option 3 for now ... push it to our OG destination now, we'll move it from there later").@github/squad-cli/@github/squad-sdkis the leading candidate, pending confirmation from GitHub's npm org owners. This PR is not part of the 2.0.0 release path.What
Moves Squad's npm distribution identity behind a single source of truth,
scripts/release/distribution-identity.json, plus a re-runnable codemod,scripts/rename-distribution-identity.mjs, and applies it to rename@bradygaster/squad-cli/@bradygaster/squad-sdkto a placeholder target (@squad/cli/@squad/sdk). Existing installs keep working: the CLI recognizes the legacy names, andsquad upgrade --self(and the update banner) removes a legacy global install before installing the new package. The Homebrew tap (bradygaster/homebrew-squad) and WinGet ID (bradygaster.Squad) are recorded in the identity file but deliberately left unchanged. Nothing is published, deprecated, or dispatched.Why
Requested by Tamir: move packages off
bradygaster, then deprecate the old names once the replacements are live. Because the final scope is undecided, the rename is parameterized so retargeting is one JSON edit plusnode scripts/rename-distribution-identity.mjs --write --from <old>(and the two constants inpackage-identity.ts).How
distribution-identity.jsonholdscurrentandlegacynames for npm CLI/SDK, the Homebrew tap and the WinGet ID. The codemod rewrites every separator form (/,%2F, escaped, path segments), version-anchored tarball names (bradygaster-squad-cli-${VERSION}.tgztosquad-cli-${VERSION}.tgz), and skips preserved history: CHANGELOGs, blog,.squad/,.github/aw/,.changeset/, published-tarball fixtures, the upgrade-matrix fixture, and uninstall/"Upgrading from" lines. With no arguments it is a check (exit 1 if retired names remain outside preserved paths); it reports 0.packages/squad-cli/src/cli/core/package-identity.ts, zero dependencies): current/legacy names,isKnownCliPackageSpec,getInstalledCliPackageName. Used byupgrade.ts(self-upgrade command, dist-tag lookup, agent-stamp normalization),mcp-root.ts(legacy MCP entries still count as Squad-managed),mcp-spec.ts, andself-update.ts.policy-gates.mjsnow builds its verified-tarball allowance from the identity (packTarballPrefix), andtest/publish-policy.test.tsimports that same regex, so a future retarget can't silently break the gate.workspace-lockfile.mjs,build-manifest.mjs(baseline lookup falls back to legacy names) andverify-team-isolation.mjsalso read it.scripts/release/verify-publish-evidence.mjsidentified the CLI withname.endsWith('squad-cli'), which skipped the CLI-to-SDK pin check for some names; it now compares with the exact expected name.get-started/package-renameguide (uninstall-then-install for npm/pnpm/yarn,upgrade --selfmigration, maintainer retarget steps), plus notes in README, README.zh, CLI README and installation.npx changeset add/.changeset/*.md, directCHANGELOG.mdentry for maintainers, orskip-changeloglabel for no user-facing changes)PR Readiness Checklist
Branch & Commit
dev(notmain)dev(git fetch upstream && git rebase upstream/dev)git diff --cached --stat)Build & Test
npm run buildpassesnpm testpasses (all tests green) — see test summary below; remaining local failures are pre-existing ondevor environmentalnpm run lintpasses (type check clean)npm run lint:eslintpassesTest output summary (Windows, local):
SKIP_BUILD_BUMP=1 npm run build: passed.npm run lint: passed.npm run lint:eslint: passed (0 errors, warnings only).node scripts/release/policy-gates.mjs: all 7 gates passed (workspace-integrity, prerelease-guard, node-security-floor, publish-policy, publish-allowlist, changelog-heading, changeset-drain).node scripts/rename-distribution-identity.mjs: 0 files still reference retired identities.node scripts/check-shebang-eol.mjs: passed.npx vitest run test/publish-policy.test.ts test/package-identity.test.ts test/squad-20-preview-tarball-matrix.test.ts test/standalone-release-workflow.test.ts test/verify-preview-evidence.test.ts test/cli/upgrade.test.ts test/template-sync.test.ts: 7 files passed, 602 passed, 50 skipped.npm test: the parallel run on this machine hit widespread 5s timeouts under load. Rerunning the non-timeout failures in isolation left 4 failures incli-packaging-smoke(forced-missing node-pty),claude-v2-review-fixes(2: backtick/<filenames, concurrent lockout) andfs-storage-symlinked-root; the same 4 fail identically on a cleandevcheckout (e6ec5130), so they are pre-existing Windows issues. gh-aw compile suites fail locally with "Compilation requires gh-aw v0.91.5 with matching immutable action pins" (environmental; this PR touches no gh-aw sources or lock files). CI on Linux is authoritative.Changeset
npx changeset add(ifpackages/squad-sdk/src/orpackages/squad-cli/src/changed)CHANGELOG.mdentry (maintainers only — write-protected for external contributors)skip-changeloglabel applied (if no user-facing changes)Docs
Exports
Breaking Changes
Yes, once merged and published: the npm package names change. Global installs of the old CLI and both packages can't coexist (both own the
squadbin), sosquad upgrade --selfuninstalls the legacy package first; users who installed manually follow the uninstall-then-install steps in the package-rename guide. SDK consumers must update their dependency name. The old@bradygasterpackages are not deprecated or removed by this PR; deprecation is a separate step after the replacements are published and verified.Waivers
Waived: "PR is not in draft mode", reason: blocked on npm scope ownership and on the decision to ship 2.0.0 under
@bradygaster; approved by: pending.Waived: "
npm testpasses", reason: local Windows failures are pre-existing ondev(verified) or environmental (gh-aw pins, load timeouts); relying on Linux CI, approved by: pending.