[thedogwiththedataonit]

Update 2026-10-16: rebased on main 2c1deff (0.16.0 + canvas session commands + canonical payload contracts + Loops export deadlines).

• Conflicts: CHANGELOG.md (this PR's notes sit under ## Unreleased above main's canvas note and 0.16.0), skills/brew-cli/SKILL.md (kept the count-free line), docs/commands/README.md (regenerated, 149 commands). package.json keeps main's SDK git pin and trustedDependencies; no dependency change here, so bun install --frozen-lockfile works as on main.
• New commit: README, the brew-cli skill, docs --agent and CHANGELOG no longer name the brew.new launcher package (not on npm, name not reserved); they show npx -y @brew.new/cli@<version>.
• Checks (frozen install from main's lockfile, SDK at a5ce43d): tsc ✓ · lint ✓ · test 56 files / 732 tests ✓ · generated types fresh ✓ · docs:commands:check ✓ · generate:skills:check ✓ · build + bin smoke ✓ · smoke:signals ✓.
• Chain: Project foundations + mcp install (C1) #44 → Login through the browser (session flow) (C3) #53 → send by key, app-emails, trigger keys (C2, 0.18.0) #54 → init + the brew.new / create-brew launchers (C4, 0.19.0) #55 → migrate resend (C5, 0.20.0): move a Resend account and codebase to Brew #61 (migrate resend).

Summary

First CLI step of the DX push (plan wave 0, "brew-cli C1"): the libraries init and migrate will stand on, a launcher-aware invocation prefix, and a purely local brew-cli mcp install.

brew-cli mcp install

• Merges a brew entry into each client's MCP config and keeps every other server and setting (indentation too):

  Client	project (default)	user (--scope user)
  Cursor	.cursor/mcp.json {mcpServers:{brew:{url}}}	~/.cursor/mcp.json
  VS Code	.vscode/mcp.json {servers:{brew:{type:"http",url}}}	profile mcp.json
  Claude Code	.mcp.json {mcpServers:{brew:{type:"http",url}}}	prints claude mcp add --scope user …
  Gemini CLI	.gemini/settings.json {mcpServers:{brew:{httpUrl}}}	~/.gemini/settings.json
  Devin Desktop (Windsurf)	user only, explicit	~/.config/devin/mcp_config.json {url} ($XDG_CONFIG_HOME, %APPDATA%\devin on Windows)
  Codex	user only, explicit	~/.codex/config.toml [mcp_servers.brew] (appended once, $CODEX_HOME honoured)

• Default clients come from .cursor/, .vscode/, .claude/ or CLAUDECODE=1, .gemini/. If .windsurf/, .devin/, .codex/ or CODEX_* shows up, that client is reported manual with its snippet and written only when you name it. If no client is found, the command exits 2.
• --auth oauth (default) writes the URL only. --auth env adds Authorization: Bearer ${env:BREW_API_KEY} (Cursor, VS Code, Windsurf), Bearer ${BREW_API_KEY} (Claude Code, Gemini) or Codex's bearer_token_env_var. It never writes a literal key, and a test checks that.
• A JSONC config (comments or trailing commas) or broken JSON is never rewritten: you get manual plus a snippet. --print and --dry-run write nothing.
• The MCP URL is the --api-url origin + /api/mcp. The Cursor deeplink is byte-identical to brew-v2 lib/mcp/handoff.ts#buildCursorInstallUrl (base64url, unpadded). The VS Code deeplink is vscode:mcp/install?<encodeURIComponent(JSON)>.
• JSON output: { mcpUrl, dryRun, clients: [{ client, path?, action: created|updated|unchanged|manual|printed, deeplink?, snippet?, note?, nextStep? }] }. mcpUrl, dryRun, snippet, note and nextStep (codex mcp login brew after a Codex OAuth entry) are additions to the planned shape.
• An existing brew entry is never replaced: equal settings report unchanged, other settings come back manual with the snippet. A config that is a symbolic link is written through only when its target stays in the project (or the home directory for user files).
• Command class write, sdkMethod: null, no route, no derivedFrom, the same as config. Registry invariants and both parity sentinels pass with no new skips.

src/lib/project/ (no new runtime dependency)

package-manager, monorepo, fs-writer (create-only, managed hashes, block upsert, CRLF, atomic writes, modes, dry-run plans with diffs), env-file (round-trips byte for byte; adds or fills, never replaces or prints a value; refuses NEXT_PUBLIC_/VITE_/PUBLIC_/EXPO_PUBLIC_ for secrets), state (brew.json with hand validation, stable order, unknown keys preserved; JSON Schema shipped in schemas/brew.json at the $schema URL), gitignore (git check-ignore -q through the spawn seam, plus a fallback parser), diff, vendor-http (bounded like rawFetch, never recorded in ctx.transport, VENDOR_ERROR {vendor,status} with credentials redacted, exits 1, bounded retry-after on 429). CliIo gains optional spawn, openUrl and cwd.

Invocation prefix

getInvocationPrefix(env) reads BREW_CLI_INVOKED_AS and falls back to brew-cli for anything that isn't plain shell words. It now leads confirmCommand, the confirm envelope's command, retryCommand, and the "run … login", types --check and preview-poll hints, plus the usage-error "see …" hints.

Skills, metadata, docs

• scripts/generate-skills.ts embeds skills/**/SKILL.md into src/generated/skills.ts. generate:skills:check runs in CI, release and bun run check.
• The brew-cli skill documents mcp install and no longer hard-codes a command count.
• New npm keywords: mcp, model-context-protocol, transactional-email, resend, resend-alternative, react-email, ai-agent, agents, auth-emails (email was already present). files now includes schemas.
• README section, CHANGELOG Unreleased entry, regenerated docs/commands/README.md.

Review round 1 (Greptile, commit 5912641)

Fixes for all 8 Greptile findings:

• Codex configs that already define mcp_servers.brew (quoted names, dotted keys, sub-tables, inline tables) now come back manual instead of getting a second table.
• Symlinked configs are written through to the target, and the link stays.
• KEY= # todo reads as empty.
• Mixed line endings round-trip byte for byte.
• Credentials are redacted before vendor error text is cut to length.
• ensureIgnored reports conflicts for paths that a later rule re-includes.
• Schema path rules match the CLI's validator.
• Brace globs expand in workspace patterns.

One addition of my own: sensitive writes (.env.local) carry no dry-run diff.

Round 2 (commit 40df837): the Codex checks now run on the TOML structure, with comments stripped and string values blanked. A comment or string that only mentions mcp_servers.brew no longer blocks the install.

Not in this PR

• Reserving npm names brew.new / create-brew: that is a publish, which this PR does not do.
• mcp install does not write brew.json#mcp. init (C4) owns that file.

Test plan

• bun run tsc
• bun run lint
• bun run test: 52 files, 688 tests. Covers project libs on fixture projects (tests/fixtures/projects/*: pnpm+turbo, npm workspaces, nx, yarn berry PnP, yarn classic, bun, deno, next app, no package.json); mcp install end to end on temp dirs (create, merge, unchanged, JSONC manual, broken JSON, dry-run, print, user scope, Codex append/unchanged, CODEX_HOME, --api-url, monorepo root, no literal key, deeplink bytes); invocation prefix in confirm/retry envelopes; generate-skills --check. Everything runs in-process under MSW (onUnhandledRequest: 'error'); one gitignore test calls the real git binary when it is installed.
• bun run docs:commands:check, bun run generate:skills:check
• bun run build, bin smoke, bun run smoke:signals

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Confidence Score: 2/5

Hold merging until workspace selection and the outstanding Windows and pnpm install failures are fixed.

Findings

1.  Setup targets the wrong package ▶
2.  Windows SDK installs fail ▶
3.  pnpm root installs fail ▶
4.  Block edits change other lines ▶
5.  Ignore plans report false success ▶
6.  Workspace lists lose their folders ▶
7.  Workspace folders disappear ▶

Fix with agent prompt

### Issue 1
src/lib/project/monorepo.ts:207-211
`expandGlob` misses valid workspace patterns such as `apps/[ab]*` because `segmentRegex` escapes the brackets instead of matching either character. Patterns containing only a character choice also take the literal-directory branch.

This loses the current workspace and its app candidates. PR #55's `detectProject` then falls back to the monorepo root, so running `init` inside an app can generate files and install dependencies in the wrong package. Support character choices, or return a clear unsupported-pattern error instead of silently finding no matches.

### Issue 2
src/lib/project/process.ts:36-38
`defaultSpawn` passes commands directly to `nodeSpawn` with `shell: false`. If Windows provides npm through the usual `npm.cmd` file, this cannot start it. PR #55's `src/lib/init/pipeline.ts` passes the `npm` command from `addCommand` straight to this helper, so `init` fails to install the SDK and leaves its generated imports without their dependency.

Add a Windows-safe way to run these command files while preserving argument quoting.

### Issue 3
src/lib/project/package-manager.ts:260-264
When no workspace is selected, `addCommand` produces `pnpm add <package>`. At a pnpm workspace root, pnpm refuses this without `--workspace-root`.

PR #55's `planInstall` reaches this case when the root is the selected app, including `init --app .`. SDK installation then fails, leaving generated imports without their dependency. Add an explicit root-workspace option and have that caller pass it.

### Issue 4
src/lib/project/fs-writer.ts:473-478
`upsertBlock` changes line endings outside its managed block when a file mixes LF and CRLF. `applyBlock` normalizes the whole file, then `withEol` changes every line to CRLF if any original line used CRLF. This creates unrelated edits and breaks the helper's promise to leave surrounding text untouched. Preserve the original text outside the block.

### Issue 5
src/lib/project/gitignore.ts:228-233
`ensureIgnored` reports a path as `added` during a dry run even when the writer refuses the edit. A `.gitignore` link pointing outside the project returns `refused`, but this branch still checks the proposed text and reports success. The plan therefore disagrees with the real run. Treat `refused` as a conflict before checking the planned rules.

### Issue 6
src/lib/project/monorepo.ts:131-133
`parsePnpmWorkspaceYaml` silently drops a valid bracket list split across lines, such as `packages: ["services/*",` followed by `"modules/*"]`. It reads bracket lists only when they end on the same line; later entries must start with `-`. `findMonorepo` then substitutes conventional folders, losing the actual workspace and app candidates. Read multi-line bracket lists or report that this form is unsupported instead of substituting other folders.

### Issue 7
src/lib/project/monorepo.ts:133-134
`parsePnpmWorkspaceYaml` splits quoted patterns at every comma. A valid list such as `packages: ['{apps,packages}/*']` becomes two broken patterns before `expandBraces` sees it, so neither folder yields any workspace packages. `resolveProjectRoot` then loses the current workspace and its app candidates, including for the `init` caller in PR #55.

Split only between YAML list items, not inside quoted strings.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds local mcp install, project-file helpers, launcher-aware command hints, and embedded agent skills.

• Developers can add Brew MCP to supported editor configs from the CLI.
• Project helpers can identify package managers and workspace roots.
• Project helpers can safely update files and keep project state.
• Project commands can make bounded requests to outside services.
• Printed follow-up commands can use the package runner that launched the CLI.
• The CLI build now carries skill files as generated source.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[mcp install] --> B[Resolve project root]
  B --> C[Select named or detected clients]
  C --> D{Print or report only?}
  D -->|Yes| E[Return snippets]
  D -->|No| F[Read client config]
  F --> G{Safe to merge?}
  G -->|No| E
  G -->|Yes| H[Plan or write Brew entry]
  H --> I[Return actions and next steps]

Loading

_{Reviews (9) · Last reviewed commit: "docs(changelog): #44's entries are unrel..." · Reviewed by Greptile}

[greptile-apps]

Block edits change other lines

upsertBlock changes line endings outside its managed block when a file mixes LF and CRLF. applyBlock normalizes the whole file, then withEol changes every line to CRLF if any original line used CRLF. This creates unrelated edits and breaks the helper's promise to leave surrounding text untouched. Preserve the original text outside the block.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/fs-writer.ts
Line: 473-478

Comment:
**Block edits change other lines**

`upsertBlock` changes line endings outside its managed block when a file mixes LF and CRLF. `applyBlock` normalizes the whole file, then `withEol` changes every line to CRLF if any original line used CRLF. This creates unrelated edits and breaks the helper's promise to leave surrounding text untouched. Preserve the original text outside the block.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Ignore plans report false success

ensureIgnored reports a path as added during a dry run even when the writer refuses the edit. A .gitignore link pointing outside the project returns refused, but this branch still checks the proposed text and reports success. The plan therefore disagrees with the real run. Treat refused as a conflict before checking the planned rules.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/gitignore.ts
Line: 228-233

Comment:
**Ignore plans report false success**

`ensureIgnored` reports a path as `added` during a dry run even when the writer refuses the edit. A `.gitignore` link pointing outside the project returns `refused`, but this branch still checks the proposed text and reports success. The plan therefore disagrees with the real run. Treat `refused` as a conflict before checking the planned rules.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Workspace lists lose their folders

parsePnpmWorkspaceYaml silently drops a valid bracket list split across lines, such as packages: ["services/*", followed by "modules/*"]. It reads bracket lists only when they end on the same line; later entries must start with -. findMonorepo then substitutes conventional folders, losing the actual workspace and app candidates. Read multi-line bracket lists or report that this form is unsupported instead of substituting other folders.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/monorepo.ts
Line: 131-133

Comment:
**Workspace lists lose their folders**

`parsePnpmWorkspaceYaml` silently drops a valid bracket list split across lines, such as `packages: ["services/*",` followed by `"modules/*"]`. It reads bracket lists only when they end on the same line; later entries must start with `-`. `findMonorepo` then substitutes conventional folders, losing the actual workspace and app candidates. Read multi-line bracket lists or report that this form is unsupported instead of substituting other folders.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Windows SDK installs fail

defaultSpawn passes commands directly to nodeSpawn with shell: false. If Windows provides npm through the usual npm.cmd file, this cannot start it. PR #55's src/lib/init/pipeline.ts passes the npm command from addCommand straight to this helper, so init fails to install the SDK and leaves its generated imports without their dependency.

Add a Windows-safe way to run these command files while preserving argument quoting.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/process.ts
Line: 36-38

Comment:
**Windows SDK installs fail**

`defaultSpawn` passes commands directly to `nodeSpawn` with `shell: false`. If Windows provides npm through the usual `npm.cmd` file, this cannot start it. PR #55's `src/lib/init/pipeline.ts` passes the `npm` command from `addCommand` straight to this helper, so `init` fails to install the SDK and leaves its generated imports without their dependency.

Add a Windows-safe way to run these command files while preserving argument quoting.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Workspace folders disappear

parsePnpmWorkspaceYaml splits quoted patterns at every comma. A valid list such as packages: ['{apps,packages}/*'] becomes two broken patterns before expandBraces sees it, so neither folder yields any workspace packages. resolveProjectRoot then loses the current workspace and its app candidates, including for the init caller in PR #55.

Split only between YAML list items, not inside quoted strings.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/monorepo.ts
Line: 133-134

Comment:
**Workspace folders disappear**

`parsePnpmWorkspaceYaml` splits quoted patterns at every comma. A valid list such as `packages: ['{apps,packages}/*']` becomes two broken patterns before `expandBraces` sees it, so neither folder yields any workspace packages. `resolveProjectRoot` then loses the current workspace and its app candidates, including for the `init` caller in PR #55.

Split only between YAML list items, not inside quoted strings.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

pnpm root installs fail

When no workspace is selected, addCommand produces pnpm add <package>. At a pnpm workspace root, pnpm refuses this without --workspace-root.

PR #55's planInstall reaches this case when the root is the selected app, including init --app .. SDK installation then fails, leaving generated imports without their dependency. Add an explicit root-workspace option and have that caller pass it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/package-manager.ts
Line: 260-264

Comment:
**pnpm root installs fail**

When no workspace is selected, `addCommand` produces `pnpm add <package>`. At a pnpm workspace root, pnpm refuses this without `--workspace-root`.

PR #55's `planInstall` reaches this case when the root is the selected app, including `init --app .`. SDK installation then fails, leaving generated imports without their dependency. Add an explicit root-workspace option and have that caller pass it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Setup targets the wrong package

expandGlob misses valid workspace patterns such as apps/[ab]* because segmentRegex escapes the brackets instead of matching either character. Patterns containing only a character choice also take the literal-directory branch.

This loses the current workspace and its app candidates. PR #55's detectProject then falls back to the monorepo root, so running init inside an app can generate files and install dependencies in the wrong package. Support character choices, or return a clear unsupported-pattern error instead of silently finding no matches.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/project/monorepo.ts
Line: 207-211

Comment:
**Setup targets the wrong package**

`expandGlob` misses valid workspace patterns such as `apps/[ab]*` because `segmentRegex` escapes the brackets instead of matching either character. Patterns containing only a character choice also take the literal-directory branch.

This loses the current workspace and its app candidates. PR #55's `detectProject` then falls back to the monorepo root, so running `init` inside an app can generate files and install dependencies in the wrong package. Support character choices, or return a clear unsupported-pattern error instead of silently finding no matches.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.