@loopstack/cli 0.17.0 → 0.19.0

package/fixtures/app/CLAUDE.md

@@ -6,7 +6,7 @@ This is a [Loopstack](https://loopstack.ai) app — a NestJS backend where AI wo
 
 - `src/app.module.ts` — mounts `LoopstackModule.forRoot()` plus your app modules
 - `src/hello/` — a complete example: `hello.module.ts` (`@StudioApp` groups workflows into an app) and `hello.workflow.ts` (a minimal workflow)
-- `docker-compose.yml` — Postgres, Redis, and Studio (http://localhost:5173)
+- `docker-compose.yml` — Postgres + Redis (Studio is a separate, optional `docker-compose.studio.yml` on http://localhost:5173; you don't need it — use the CLI below)
 - `.env` — configuration; add API keys here when a module needs them
 
 ## The feedback loop — use the CLI, not guesswork
@@ -17,12 +17,16 @@ The `loopstack` CLI talks to the running backend (`npm run start:dev`, http://lo
 loopstack list                        # what can be run right now
 loopstack run <workflow> --arg k=v    # run it, streamed live; --json for machine-readable output
 loopstack runs                        # recent runs, waiting-for-input first
-loopstack runs <run-id> --follow      # audit trail; reattach to a waiting run and answer prompts
+loopstack runs <run-id>               # one run's audit trail (+ pendingPrompt under --json)
+loopstack answer <run-id> --arg k=v   # answer a waiting run's prompt non-interactively
+loopstack attach <run-id>             # rejoin a run live and answer its prompts interactively
 loopstack watch --json                # NDJSON event firehose while you develop
 ```
 
 Exit codes: `0` completed, `1` failed, `2` connection/config error, `3` waiting for input in a non-interactive shell. After changing code, the dev server reloads automatically — rerun the workflow to verify.
 
+When a run exits `3`, it parked on a human question. Close the loop instead of stopping: read the question with `loopstack runs <run-id> --json` (the `pendingPrompt` field carries the description, the expected answer schema, and the transition), ask the human for their answer, submit it with `loopstack answer <run-id> --arg key=value`, then re-check `loopstack runs <run-id>` for the outcome. Never invent an answer to a human question yourself.
+
 ## Writing workflows
 
 Follow `src/hello/hello.workflow.ts` as the canonical example:
@@ -33,6 +37,16 @@ Follow `src/hello/hello.workflow.ts` as the canonical example:
 - Documents are classes with `@Document({ schema })` (zod) saved via `this.documentStore.save(SomeDocument, data)` — they are what Studio renders.
 - Tools are NestJS providers with `@Tool({ name })`, implementing `protected async handle(args, ctx, options?): Promise<ToolEnvelope>`.
 
+## Testing
+
+Tests are ordinary vitest tests that run the real engine in-process — no backend, no database:
+
+- `runWorkflow(MyWorkflow, args, { providers, answers })` from `@loopstack/testing` executes the workflow and returns `{ status, path, result, documents, document(key) }` for assertions. Script HITL input with `answers: { waitTransitionName: payload }`; sub-workflows run inline.
+- `testTool().forTool(MyTool)` unit-tests a tool's `handle()` in isolation.
+- For deterministic LLM/tool regression tests, record a live run (`loopstack run <workflow> --trace`, then `loopstack runs <run-id> --record fixture.json`) and pass `replay: replay('fixture.json')` to `runWorkflow`. Omit `replay` to test against real providers — keep those assertions structural and run them on demand, not in CI.
+
+Write workflow tests for every non-trivial workflow you build. Guide: https://loopstack.ai/docs/build/testing
+
 ## Learning more
 
 - Docs: https://loopstack.ai/docs — for agents, the full corpus is at https://loopstack.ai/llms.txt (route via titles, fetch what you need)

package/fixtures/app/README.md

@@ -5,16 +5,22 @@ Scaffolded with `loopstack create`.
 ## Quickstart
 
 ```bash
-docker compose up -d     # Postgres, Redis, and Studio
+docker compose up -d     # Postgres + Redis
 npm run start:dev        # the backend on http://localhost:3000
 ```
 
-Open Studio at [http://localhost:5173](http://localhost:5173), or run the hello workflow from the terminal:
+Run the hello workflow from the terminal:
 
 ```bash
 npx @loopstack/cli run hello --arg name=You
 ```
 
+Prefer a visual UI? Start Studio (optional) and open [http://localhost:5173](http://localhost:5173):
+
+```bash
+docker compose -f docker-compose.studio.yml up -d
+```
+
 ## Next steps
 
 - Build your first workflow: https://loopstack.ai/docs

package/fixtures/app/docker-compose.studio.yml

@@ -0,0 +1,10 @@
+name: loopstack
+
+services:
+  studio:
+    image: ghcr.io/loopstack-ai/loopstack-studio:latest
+    pull_policy: always
+    ports:
+      - '5173:3000'
+    environment:
+      VITE_API_URL: ${VITE_API_URL:-http://localhost:3000}

package/fixtures/app/docker-compose.yml

@@ -20,14 +20,6 @@ services:
     volumes:
       - redis_data:/data
 
-  studio:
-    image: ghcr.io/loopstack-ai/loopstack-studio:latest
-    pull_policy: always
-    ports:
-      - '5173:3000'
-    environment:
-      VITE_API_URL: ${VITE_API_URL:-http://localhost:3000}
-
 volumes:
   postgres_data:
   redis_data:

package/fixtures/app/env.example

@@ -2,6 +2,11 @@
 
 # PORT=3000
 
+# Point at any Postgres / Redis with a single URL (managed, hosted, or your own),
+# or use the discrete vars below. A URL, when set, takes precedence.
+# DATABASE_URL=postgres://postgres:admin@localhost:5432/postgres
+# REDIS_URL=redis://localhost:6379
+
 # DATABASE_HOST=localhost
 # DATABASE_PORT=5432
 # DATABASE_USERNAME=postgres

package/fixtures/app/src/main.ts

@@ -3,6 +3,9 @@ import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
+  // Graceful shutdown: on SIGTERM/SIGINT the BullMQ worker finishes in-flight
+  // transitions before the process exits, instead of stalling them.
+  app.enableShutdownHooks();
   await app.listen(process.env.PORT ?? 3000);
 }
 void bootstrap();

package/package.json

@@ -2,7 +2,7 @@
   "name": "@loopstack/cli",
   "displayName": "Loopstack CLI",
   "description": "Run, trace, and watch Loopstack workflows from the terminal",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "license": "MIT",
   "author": {
     "name": "Jakob Klippel",
@@ -26,8 +26,8 @@
     "watch": "tsc -p tsconfig.build.json --watch"
   },
   "dependencies": {
-    "@loopstack/client": "^0.37.1",
-    "@loopstack/contracts": "^0.37.0",
+    "@loopstack/client": "^0.39.0",
+    "@loopstack/contracts": "^0.39.0",
     "commander": "^15.0.0",
     "picocolors": "^1.1.1"
   },

package/dist/hitl/editor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../src/hitl/editor.ts"],"names":[],"mappings":"AAiCA,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS7G;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAU7E;AAQD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAqBzG"}

package/dist/hitl/editor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"editor.js","sourceRoot":"","sources":["../../src/hitl/editor.ts"],"names":[],"mappings":"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"}