Repository navigation
feat(release): parameterize npm distribution identity (rename off @bradygaster, scope TBD) - #2536
Draft
tamirdresher wants to merge 3 commits into
Draft
tamirdresher wants to merge 3 commits into
tamirdresher wants to merge 3 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>
Comment on lines
60
to
+66
| `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/). |
Comment on lines
69
to
+72
| 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. |
Contributor
🔴 Impact Analysis — PR #2536Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (8 files)
copilot-config (4 files)
docs (61 files)
root (63 files)
scripts (26 files)
squad-cli (88 files)
squad-sdk (20 files)
templates (8 files)
tests (194 files)
|
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 3 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 | 18 check(s) still running |
Files Changed (472 files, +2355 −1870)
| 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 |
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/charter-v0.1.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: +2355 −1870
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🏗️ 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>
|
|
||
| /** Registry metadata path for a scoped name, e.g. `@squad%2Fcli`. */ | ||
| export function registryPackagePath(name: string): string { | ||
| return name.replace('/', '%2F'); |
| }); | ||
|
|
||
| it('encodes scoped names for registry URLs', () => { | ||
| expect(registryPackagePath(CLI_PACKAGE_NAME)).toBe(CLI_PACKAGE_NAME.replace('/', '%2F')); |
| ): string { | ||
| const tag: SelfUpgradeTag = typeof insiderOrTag === 'boolean' ? (insiderOrTag ? 'insider' : 'latest') : insiderOrTag; | ||
| const pkg = `@bradygaster/squad-cli@${tag}`; | ||
| const pkg = `${CLI_PACKAGE_NAME}@${tag}`; |
| case 'pnpm': return `pnpm add -g ${pkg}`; | ||
| case 'yarn': return `yarn global add ${pkg}`; | ||
| default: return `npm install -g ${pkg}`; | ||
| case 'pnpm': return `${legacy ? `pnpm remove -g ${legacy} && ` : ''}pnpm add -g ${pkg}`; |
| case 'yarn': return `yarn global add ${pkg}`; | ||
| default: return `npm install -g ${pkg}`; | ||
| case 'pnpm': return `${legacy ? `pnpm remove -g ${legacy} && ` : ''}pnpm add -g ${pkg}`; | ||
| case 'yarn': return `${legacy ? `yarn global remove ${legacy} && ` : ''}yarn global add ${pkg}`; |
| default: return `npm install -g ${pkg}`; | ||
| case 'pnpm': return `${legacy ? `pnpm remove -g ${legacy} && ` : ''}pnpm add -g ${pkg}`; | ||
| case 'yarn': return `${legacy ? `yarn global remove ${legacy} && ` : ''}yarn global add ${pkg}`; | ||
| default: return `${legacy ? `npm uninstall -g ${legacy} && ` : ''}npm install -g ${pkg}`; |
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>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.