fix(cli, wizard): make stash db push opt-in for Proxy users only

[auxesis]

Don't run stash db push unless the user explicitly states they're using CipherStash Proxy:

• SDK users (Drizzle, Supabase, plain pg) keep their encryption config in app code, so the database doesn't need a copy
• But agents reading the stash plan / stash impl prompts and skills were insisting on running it anyway.
• New --proxy / --no-proxy flags and an interactive prompt on stash init capture whether the user queries via CipherStash Proxy.
• This setting is saved to .cipherstash/context.json as usesProxy, and is honoured by stash plan, stash impl, and the wizard's post-agent step.
• All four skills (stash-cli, stash-encryption, stash-drizzle, stash-supabase) updated to be SDK focused
• db push moves into > **Using CipherStash Proxy?** callouts. A "Known gap" callout warns SDK users about the cutover precondition before they hit it.

Why

Background in #447.

The README already had the right framing — "Only required when using CipherStash Proxy" — but the agent-facing prompts and skills didn't.

Limitations

stash encrypt cutover currently requires a pending EQL config (registered via stash db push), so SDK-only users running the migrate-existing-column flow will hit a No pending EQL configuration error from cutover.

The workaround is to run stash db push once before stash encrypt cutover.

The longer term fix is to either:

• skip the EQL-config promotion entirely for SDK-only users and use a direct SQL rename, or
• auto-push from encrypt cutover for SDK-only users at cutover time

Summary by CodeRabbit

Release Notes

• New Features

  • Added --proxy and --no-proxy flags and interactive prompt during initialization to select between CipherStash Proxy or SDK querying.
  • Proxy preference is saved and persists across future plan and implementation workflows.
  • Conditional workflow steps now appear based on proxy selection; stash db push only included for Proxy users.

• Documentation

  • Updated skill guides to clarify Proxy vs SDK workflow differences and requirements.

[changeset-bot]

🦋 Changeset detected

Latest commit: f322aae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
stash	Minor
@cipherstash/wizard	Minor
@cipherstash/e2e	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@auxesis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 44 minutes and 55 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8d49f663-86e2-463e-ac94-c194d94d12fb

📥 Commits

Reviewing files that changed from the base of the PR and between bb9764d and f322aae.

📒 Files selected for processing (5)

• packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts
• packages/cli/src/commands/init/lib/read-context.ts
• packages/cli/src/commands/init/lib/setup-prompt.ts
• skills/stash-encryption/SKILL.md
• skills/stash-supabase/SKILL.md

📝 Walkthrough

Walkthrough

This PR introduces a usesProxy flag throughout the CLI and wizard to conditionally include or exclude stash db push steps based on whether users employ CipherStash Proxy or SDK-only access. The flag is captured during stash init via command-line flags or interactive prompt, persisted in .cipherstash/context.json, and propagated to influence prompt rendering and wizard execution logic.

Changes

CipherStash Proxy mode detection and conditional behavior

Layer / File(s)	Summary
Type contract updates packages/cli/src/commands/init/types.ts, packages/cli/src/commands/init/lib/write-context.ts, packages/wizard/src/lib/gather.ts	InitState, ContextFile, and GatheredContext interfaces each gain an optional usesProxy?: boolean field to track whether Proxy or SDK mode is active.
Init command --proxy flag and resolveProxyChoiceStep packages/cli/src/commands/init/index.ts, packages/cli/src/commands/init/steps/resolve-proxy-choice.ts, packages/cli/src/bin/stash.ts	stash init parses --proxy and --no-proxy flags; new resolveProxyChoiceStep shows an interactive prompt (TTY) or defaults to false (non-TTY) to set state.usesProxy, with help text updated to document the new flags.
Context file I/O and persistence packages/cli/src/commands/init/lib/read-context.ts, packages/cli/src/commands/init/lib/write-context.ts, packages/wizard/src/lib/gather.ts	readContextFile defaults missing usesProxy to false for backward compatibility; buildContextFile and buildSetupPromptContext propagate state.usesProxy to outputs; new readUsesProxyFromContext helper safely reads context files in the wizard with error handling.
Plan and impl command state builders packages/cli/src/commands/plan/index.ts, packages/cli/src/commands/impl/index.ts	Both command context builders now set InitState.usesProxy from the loaded context, defaulting to false, so downstream prompts respect user preference.
Setup prompt conditional rendering packages/cli/src/commands/init/lib/setup-prompt.ts	SetupPromptContext now includes usesProxy; implement-mode step lists for new columns, rollout, and cutover conditionally add Proxy-specific stash db push and schema operations; plan-mode prose for rollout/cutover/complete workflows conditionally includes or omits db push guidance and step details based on proxy mode.
Wizard post-agent conditional execution packages/wizard/src/lib/post-agent.ts	The "Push encryption config" step is now conditional: stash db push runs only when gathered.usesProxy is true; SDK-only users receive a skip-notification log instead.
Test coverage packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts, packages/wizard/src/__tests__/post-agent.test.ts	Test fixtures updated with usesProxy field; new test suite validates prompt output differences when usesProxy toggles across implement and plan modes; post-agent tests verify command invocations (bunx/npx) and skip behavior based on proxy mode.
Documentation .changeset/proxy-only-db-push.md, skills/stash-cli/SKILL.md, skills/stash-drizzle/SKILL.md, skills/stash-encryption/SKILL.md, skills/stash-supabase/SKILL.md	Changeset and skill docs clarify that stash db push applies only to Proxy users; SDK-only sections omit the step. Added "Known gap" notes documenting that stash encrypt cutover requires pending EQL configuration (workaround: run stash db push once before cutover for SDK users). Five-step migrate-columns flow clarified with explicit dual-write detection and cutover plan separation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Make agents less insistent on running stash db push when not using Proxy #447: This PR implements the usesProxy flag and conditional logic to suppress stash db push steps for non-Proxy SDK users, directly addressing the feature request to avoid showing Proxy-specific workflows to SDK-only developers.

Possibly related PRs

• cipherstash/stack#427: Both PRs modify the init/plan workflow architecture and SetupPromptContext rendering logic.
• cipherstash/stack#387: Both PRs modify the wizard's runPostAgentSteps encryption-config db push step in packages/wizard/src/lib/post-agent.ts.

Suggested reviewers

• calvinbrewer
• coderdan

Poem

🐰 A proxy choice, so neatly made—
SDK users, no db push cascade!
Init asks "which way?", and stores it plain,
Prompts bloom or wilt by that simple chain. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: making stash db push conditional on proxy usage rather than a default requirement for all users.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/make-agents-less-insistent-on-stash-db-push

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cli/src/commands/init/lib/read-context.ts`:
- Around line 40-45: Normalize the usesProxy field to a strict boolean when
returning the parsed context in read-context.ts: instead of forwarding any
non-nullish value from parsed, set usesProxy to true only if parsed.usesProxy is
exactly the boolean true (e.g., parsed.usesProxy === true), otherwise false;
update the return object in the block that currently spreads ...parsed and
references usesProxy and ensure this change is made where isContextFile(parsed)
is checked.

In `@packages/cli/src/commands/init/lib/setup-prompt.ts`:
- Around line 300-303: The cutover step text "4. **Switch the schema, then
cutover.**" currently omits the SDK-only workaround for missing pending EQL
config; update that string (and any duplicate cutover instruction blocks with
the same heading) to append a short workaround note instructing SDK users to run
the DB push command to register a pending EQL configuration before cutover
(e.g., run the equivalent of `stash db push` to create the pending config) or
follow the manual pending-config registration if they see "No pending EQL
configuration", so cutover won't fail when not using the Proxy.

In `@skills/stash-encryption/SKILL.md`:
- Around line 662-695: Update the CLI sequence so SDK-only users run the
required database schema push before the cutover: insert a step invoking "stash
db push" (or note to run it in CI) immediately before "stash encrypt cutover
--table users --column email" in the example block, and add a short
parenthetical reminder near the "stash encrypt cutover" and "stash encrypt
backfill" commands that SDK-only deployments must run "stash db push" once to
ensure the schema/column rename is present; reference the "stash encrypt
backfill", "stash encrypt cutover", and "stash db push" commands when making the
change.

In `@skills/stash-supabase/SKILL.md`:
- Around line 555-558: Fix the MD028 markdownlint error by removing the blank
line inside the blockquote that begins with "**Known gap (SDK-only users):**"
and the subsequent "**Using CipherStash Proxy?**" lines in SKILL.md; ensure each
blockquote line is contiguous (no empty lines between lines starting with ">")
so the two quoted paragraphs are either merged into one continuous blockquote or
split correctly with an explicit end to the blockquote before any non-quoted
content.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1d64123e-3f95-4dbc-9652-828c231483c9

📥 Commits

Reviewing files that changed from the base of the PR and between 71e8888 and bb9764d.

📒 Files selected for processing (18)

• .changeset/proxy-only-db-push.md
• packages/cli/src/bin/stash.ts
• packages/cli/src/commands/impl/index.ts
• packages/cli/src/commands/init/index.ts
• packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts
• packages/cli/src/commands/init/lib/read-context.ts
• packages/cli/src/commands/init/lib/setup-prompt.ts
• packages/cli/src/commands/init/lib/write-context.ts
• packages/cli/src/commands/init/steps/resolve-proxy-choice.ts
• packages/cli/src/commands/init/types.ts
• packages/cli/src/commands/plan/index.ts
• packages/wizard/src/__tests__/post-agent.test.ts
• packages/wizard/src/lib/gather.ts
• packages/wizard/src/lib/post-agent.ts
• skills/stash-cli/SKILL.md
• skills/stash-drizzle/SKILL.md
• skills/stash-encryption/SKILL.md
• skills/stash-supabase/SKILL.md