Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Add `spree shell` command for interactive container access (#14286)

Damian Legawiec2174f67734f5
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
index a17f6e1b86..7c151a5155 100644
--- a/docs/developer/cli/quickstart.mdx
+++ b/docs/developer/cli/quickstart.mdx
@@ -141,6 +141,15 @@ Open a Rails console.
spree console
```
+### `spree shell`
+
+Open an interactive bash shell inside the web container — the system-shell sibling of `spree console` (Rails) and `spree db:console` (psql). If the web container is down, it starts a one-off container against the same volumes instead. For one-off non-interactive commands, use `spree exec`.
+
+```bash
+spree shell
+spree bash # alias
+```
+
### `spree open`
Open the admin dashboard in the browser.
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
index 6c2b3b216d..9913d1f029 100644
--- a/packages/cli/CHANGELOG.md
+++ b/packages/cli/CHANGELOG.md
@@ -1,5 +1,11 @@
# @spree/cli
+## 2.3.9
+
+### Patch Changes
+
+- Add `spree shell` (alias: `spree bash`) — open an interactive bash shell inside the web container, the system-shell sibling of `spree console` (Rails) and `spree db:console` (psql). When the web container is down — a crash-looping stack is exactly when a shell is most useful — it falls back to a one-off container against the same volumes, with postgres cold-started and health-waited first.
+
## 2.3.8
### Patch Changes
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 6cbfe82381..0f5ce04635 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -88,6 +88,15 @@ Open an interactive Rails console inside the running container.
spree console
```
+### `spree shell`
+
+Open an interactive bash shell inside the web container. If the container is down, a one-off container is started against the same volumes instead.
+
+```bash
+spree shell
+spree bash # alias
+```
+
### `spree rspec`
Run the RSpec test suite inside the web container with `RAILS_ENV=test`. Everything after `rspec` is passed through to RSpec.
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 4ff391b086..03823e68ad 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/cli",
- "version": "2.3.8",
+ "version": "2.3.9",
"description": "CLI for managing Spree Commerce projects",
"type": "module",
"bin": {
diff --git a/packages/cli/src/commands/shell.ts b/packages/cli/src/commands/shell.ts
new file mode 100644
index 0000000000..448c5fa45c
--- /dev/null
+++ b/packages/cli/src/commands/shell.ts
@@ -0,0 +1,23 @@
+import type { Command } from 'commander'
+import { detectProject } from '../context.js'
+import { dockerComposeExecOrRun } from '../docker.js'
+
+// Open an interactive bash shell in the web container — the system-shell
+// sibling of `spree console` (Rails) and `spree db:console` (psql). One-off
+// non-interactive commands belong to `spree exec` instead.
+//
+// When web is down — a crash-looping container is exactly when a shell is
+// most useful — fall back to a one-off `compose run` shell against the same
+// volumes (its depends_on health-waits postgres).
+export function registerShellCommand(program: Command): void {
+ program
+ .command('shell')
+ .alias('bash')
+ .description('Open an interactive bash shell inside the web container')
+ .action(async () => {
+ const ctx = detectProject()
+ await dockerComposeExecOrRun(['bash'], ctx.projectDir, {
+ edgeHint: 'then open the shell',
+ })
+ })
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 762d3f3d36..efdfe196c7 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -23,6 +23,7 @@ import { registerRoutesCommand } from './commands/routes.js'
import { registerRspecCommand } from './commands/rspec.js'
import { registerSampleDataCommand } from './commands/sample-data.js'
import { registerSeedCommand } from './commands/seed.js'
+import { registerShellCommand } from './commands/shell.js'
import { registerStopCommand } from './commands/stop.js'
import { registerTaskCommand } from './commands/task.js'
import { registerUpdateCommand } from './commands/update.js'
@@ -83,6 +84,7 @@ registerRakeCommand(program)
registerTaskCommand(program)
registerRspecCommand(program)
registerConsoleCommand(program)
+registerShellCommand(program)
// Spree-specific helpers
registerUserCommand(program)
diff --git a/packages/cli/tests/shell.test.ts b/packages/cli/tests/shell.test.ts
new file mode 100644
index 0000000000..65402a93fb
--- /dev/null
+++ b/packages/cli/tests/shell.test.ts
@@ -0,0 +1,46 @@
+import { Command } from 'commander'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerShellCommand } from '../src/commands/shell'
+import { dockerComposeExecOrRun } from '../src/docker'
+
+let projectDir: string
+
+vi.mock('../src/context', () => ({
+ detectProject: () => ({ mode: 'docker', projectDir, port: 3000 }),
+}))
+
+vi.mock('../src/docker', () => ({
+ dockerComposeExecOrRun: vi.fn().mockResolvedValue(undefined),
+}))
+
+async function runShell(command: string): Promise<void> {
+ const program = new Command()
+ registerShellCommand(program)
+ await program.parseAsync([command], { from: 'user' })
+}
+
+describe('spree shell', () => {
+ beforeEach(() => {
+ projectDir = '/proj'
+ vi.clearAllMocks()
+ })
+
+ // Branching (exec vs one-off run vs monorepo-edge refusal) is covered by
+ // dockerComposeExecOrRun's own tests in docker.test.ts; here we only assert
+ // the command delegates with the right argv + edge hint.
+ it('delegates to dockerComposeExecOrRun with bash', async () => {
+ await runShell('shell')
+
+ expect(dockerComposeExecOrRun).toHaveBeenCalledWith(['bash'], '/proj', {
+ edgeHint: 'then open the shell',
+ })
+ })
+
+ it('is also invocable as `spree bash`', async () => {
+ await runShell('bash')
+
+ expect(dockerComposeExecOrRun).toHaveBeenCalledWith(['bash'], '/proj', {
+ edgeHint: 'then open the shell',
+ })
+ })
+})