feat: add interactive worker shell

dev-worker

@@ -10,7 +10,8 @@ Usage: sh ./dev-worker <worker-id> <command> [arguments...]
 
 Commands:
   up                 Start the isolated worker and wait for Nextcloud installation
-  exec <command...>  Run a command in the worker's Nextcloud container
+  exec <command...>  Run a non-interactive command in the worker's Nextcloud container
+  shell              Open an interactive shell in the worker's Nextcloud container
   logs               Print worker logs
   config             Render the resolved Compose configuration
   status             Run occ status in the worker
@@ -28,6 +29,7 @@ Environment:
   NEXTCLOUD_HOST=<hostname>  Public hostname (default: <project>.localhost)
   NEXTCLOUD_PROTOCOL=http|https Public protocol (default: https)
   NCDD_WORKSPACE=<path>     Optional directory mounted as /var/www/html/apps-extra
+  NCDD_SHELL=<command>       Interactive shell command (default: bash)
   WORKER_READY_TIMEOUT=180  Seconds to wait for a clean installation
 EOF
 }
@@ -184,6 +186,9 @@ case "$command" in
 		}
 		compose exec -T nextcloud "$@"
 		;;
+	shell)
+		compose exec nextcloud "${NCDD_SHELL:-bash}"
+		;;
 	logs)
 		compose logs --no-color "$@"
 		;;
@@ -233,4 +238,4 @@ case "$command" in
 		usage >&2
 		exit 2
 		;;
-esac
+esac

docs/apps-development.md

@@ -56,8 +56,19 @@ NCDD does not assign a primary application, manage application repositories or
 limit how many applications the workspace contains. Clones, Git worktrees and
 other source layouts are the responsibility of the caller.
 
+For an interactive development shell, use the worker command that keeps TTY
+allocation enabled:
+
+```bash
+NCDD_WORKSPACE=/tmp/workspaces/issue-123 \
+DB_TYPE=sqlite \
+sh ./dev-worker issue-123 shell
+```
+
+Set `NCDD_SHELL` if a shell other than `bash` is desired.
+
 Application-specific setup remains owned by the application repository or the
-agent operating the worker:
+agent operating the worker. Use `exec` for non-interactive commands:
 
 ```bash
 NCDD_WORKSPACE=/tmp/workspaces/issue-123 \
@@ -69,4 +80,4 @@ sh ./dev-worker issue-123 exec sh -lc \
 Worker runtime state remains under `.workers/<worker-id>`; destroying a worker
 never deletes its external workspace.
 
-⬅️ [Back to index](../README.md)
+⬅️ [Back to index](../README.md)

tests/worker/contract.bats

@@ -113,3 +113,11 @@ setup() {
 }
 
 
+
+@test "worker exposes a TTY-enabled interactive shell command" {
+	run grep -F 'compose exec nextcloud "${NCDD_SHELL:-bash}"' "$WORKER"
+	[ "$status" -eq 0 ]
+
+	run grep -F 'compose exec -T nextcloud "$@"' "$WORKER"
+	[ "$status" -eq 0 ]
+}