@loopstack/cli 0.15.1 → 0.17.0

package/dist/run/follow.js

@@ -0,0 +1,148 @@
+import pc from 'picocolors';
+import { WorkflowState } from '@loopstack/contracts/enums';
+import { CliError } from '../errors.js';
+import { formatDuration } from '../output/format.js';
+const TERMINAL_STATES = [
+    WorkflowState.Completed,
+    WorkflowState.Failed,
+    WorkflowState.Canceled,
+];
+const IDLE_STATES = [WorkflowState.Waiting, WorkflowState.Paused];
+export async function followRun(events, workflowId, out, options = {}) {
+    const startedAt = Date.now();
+    let currentPlace;
+    let placeEnteredAt = startedAt;
+    let streaming = false;
+    const endTokenLine = () => {
+        if (!streaming)
+            return;
+        out.write('\n');
+        streaming = false;
+    };
+    const finishStep = (mark = pc.green('✓')) => {
+        if (!currentPlace)
+            return;
+        endTokenLine();
+        out.write(`${mark} ${currentPlace} ${pc.dim(`(${formatDuration(Date.now() - placeEnteredAt)})`)}\n`);
+        currentPlace = undefined;
+    };
+    const outcome = (status) => ({ status, durationMs: Date.now() - startedAt });
+    const family = new Set([workflowId]);
+    const handleEvent = (event) => {
+        if (!('workflowId' in event))
+            return undefined;
+        if (event.type === 'workflow.created') {
+            if (event.parentId && family.has(event.parentId))
+                family.add(event.workflowId);
+            return undefined;
+        }
+        if (!family.has(event.workflowId))
+            return undefined;
+        switch (event.type) {
+            case 'llm.response.text_delta':
+                streaming = true;
+                out.write(event.delta);
+                break;
+            case 'llm.response.done':
+            case 'llm.response.error':
+                endTokenLine();
+                break;
+            case 'workflow.updated': {
+                if (event.workflowId !== workflowId)
+                    break;
+                if (event.place && event.place !== currentPlace) {
+                    finishStep();
+                    if (event.place !== 'end') {
+                        currentPlace = event.place;
+                        placeEnteredAt = Date.now();
+                        if (!TERMINAL_STATES.includes(event.status)) {
+                            out.write(pc.dim(`▸ ${currentPlace}\n`));
+                        }
+                    }
+                }
+                if (TERMINAL_STATES.includes(event.status)) {
+                    endTokenLine();
+                    return outcome(event.status);
+                }
+                if (IDLE_STATES.includes(event.status)) {
+                    finishStep(pc.yellow('⏸'));
+                    return 'idle';
+                }
+                break;
+            }
+        }
+        return undefined;
+    };
+    const startPrompt = () => {
+        const controller = new AbortController();
+        const pending = { controller };
+        pending.result = options.onIdle(controller.signal, (id) => {
+            pending.workflowId = id;
+        });
+        return pending;
+    };
+    const resolvesPrompt = (prompt, event) => {
+        if (event.type !== 'workflow.updated' || !('workflowId' in event))
+            return false;
+        const promptWorkflowId = prompt.workflowId ?? workflowId;
+        return event.workflowId === promptWorkflowId && !IDLE_STATES.includes(event.status);
+    };
+    let prompt = options.initiallyIdle && options.onIdle ? startPrompt() : null;
+    let pendingNext = null;
+    const pullNext = () => (pendingNext ??= events.next());
+    while (true) {
+        let event;
+        if (prompt) {
+            const raced = await Promise.race([
+                pullNext().then((result) => ({ kind: 'event', result })),
+                prompt.result.then((idle) => ({ kind: 'idle', idle })),
+            ]);
+            if (raced.kind === 'idle') {
+                prompt = null;
+                if (raced.idle === 'stop')
+                    return outcome(WorkflowState.Waiting);
+                if (raced.idle === 'external')
+                    out.write(`${pc.green('✓')} answered in Studio\n`);
+                continue;
+            }
+            pendingNext = null;
+            if (raced.result.done)
+                throw new CliError('Event stream ended before the run reached a final state.');
+            event = raced.result.value;
+            if (resolvesPrompt(prompt, event)) {
+                prompt.controller.abort();
+                const idle = await prompt.result;
+                prompt = null;
+                if (idle === 'stop')
+                    return outcome(WorkflowState.Waiting);
+                if (idle === 'external')
+                    out.write(`${pc.green('✓')} answered in Studio\n`);
+            }
+        }
+        else {
+            const { value, done } = await pullNext();
+            pendingNext = null;
+            if (done)
+                throw new CliError('Event stream ended before the run reached a final state.');
+            event = value;
+        }
+        if (event.type === 'document.created' &&
+            'workflowId' in event &&
+            family.has(event.workflowId) &&
+            options.onDocument) {
+            endTokenLine();
+            await options.onDocument(event.workflowId);
+            continue;
+        }
+        const handled = handleEvent(event);
+        if (handled === 'idle') {
+            if (!options.onIdle)
+                return outcome(WorkflowState.Waiting);
+            prompt ??= startPrompt();
+        }
+        else if (handled) {
+            return handled;
+        }
+    }
+}
+//# sourceMappingURL=follow.js.map

package/dist/run/follow.js.map

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

package/dist/run/workspace.d.ts

@@ -0,0 +1,3 @@
+import type { LoopstackClient } from '@loopstack/client';
+export declare function resolveWorkspaceId(client: LoopstackClient, workflowName: string, explicit?: string, pinned?: string): Promise<string>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/run/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/run/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASzD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/run/workspace.js

@@ -0,0 +1,26 @@
+import { SortOrder } from '@loopstack/contracts/enums';
+import { CliError } from '../errors.js';
+export async function resolveWorkspaceId(client, workflowName, explicit, pinned) {
+    if (explicit)
+        return explicit;
+    if (pinned)
+        return pinned;
+    const apps = await client.config.apps();
+    const app = apps.find((candidate) => candidate.workflows?.some((workflow) => workflow.workflowName === workflowName));
+    if (!app) {
+        const available = apps.flatMap((candidate) => candidate.workflows?.map((w) => w.workflowName) ?? []);
+        throw new CliError(`Unknown workflow "${workflowName}". Available workflows: ${available.sort().join(', ') || '(none)'}`);
+    }
+    const page = await client.workspaces.list({
+        filter: { appName: app.appName },
+        sortBy: [{ field: 'createdAt', order: SortOrder.DESC }],
+        page: 0,
+        limit: 1,
+    });
+    const existing = page.data[0];
+    if (existing)
+        return existing.id;
+    const created = await client.workspaces.create({ title: 'CLI', appName: app.appName });
+    return created.id;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/run/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/run/workspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAOxC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAuB,EACvB,YAAoB,EACpB,QAAiB,EACjB,MAAe;IAEf,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,KAAK,YAAY,CAAC,CAAC,CAAC;IACtH,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;QACrG,MAAM,IAAI,QAAQ,CAChB,qBAAqB,YAAY,2BAA2B,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CACtG,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;QACxC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;QAChC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QACvD,IAAI,EAAE,CAAC;QACP,KAAK,EAAE,CAAC;KACT,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC,EAAE,CAAC;AACpB,CAAC"}

package/fixtures/app/CLAUDE.md

@@ -0,0 +1,40 @@
+# Loopstack App
+
+This is a [Loopstack](https://loopstack.ai) app — a NestJS backend where AI workflows are code: state machines with explicit transitions, typed documents, and tools, all observable in Studio and from the CLI.
+
+## Where things live
+
+- `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)
+- `.env` — configuration; add API keys here when a module needs them
+
+## The feedback loop — use the CLI, not guesswork
+
+The `loopstack` CLI talks to the running backend (`npm run start:dev`, http://localhost:3000):
+
+```bash
+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 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.
+
+## Writing workflows
+
+Follow `src/hello/hello.workflow.ts` as the canonical example:
+
+- A workflow is a class with `@Workflow({ title, description, schema })` extending `BaseWorkflow<Args>` (the zod `schema` types and validates its args); register it in the `@StudioApp` module.
+- Transitions are methods with `@Transition({ to: 'x' })` (initial, `from` defaults to `'start'`) or `@Transition({ from: 'x', to: 'end' })` (final). Signatures: `(state, ctx)` for automatic transitions, `(state, payload, ctx)` for wait transitions. Workflow args are on `ctx.args`.
+- Transitions return nothing — mutate via `this.assignState(partial)` and publish results via `this.assignResult(partial)`. Use `async` only when the body awaits.
+- 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>`.
+
+## 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)
+- Registry of feature modules and examples (LLM providers, HITL prompts, agents, git, secrets, sandboxes): https://loopstack.ai/registry — each package README has an installation section; prefer adapting a registry example over building from scratch
+- CLI reference: https://loopstack.ai/docs/reference/cli

package/fixtures/app/README.md

@@ -0,0 +1,21 @@
+# Loopstack App
+
+Scaffolded with `loopstack create`.
+
+## Quickstart
+
+```bash
+docker compose up -d     # Postgres, Redis, and Studio
+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:
+
+```bash
+npx @loopstack/cli run hello --arg name=You
+```
+
+## Next steps
+
+- Build your first workflow: https://loopstack.ai/docs
+- Add feature modules and example workflows from the registry: https://loopstack.ai/registry

package/fixtures/app/docker-compose.yml

@@ -0,0 +1,33 @@
+name: loopstack
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_DB: ${DATABASE_NAME:-postgres}
+      POSTGRES_USER: ${DATABASE_USERNAME:-postgres}
+      POSTGRES_PASSWORD: ${DATABASE_PASSWORD:-admin}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:8-alpine
+    ports:
+      - '6379:6379'
+    command: ['redis-server', '--appendonly', 'yes']
+    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

@@ -0,0 +1,16 @@
+# All values are optional — the defaults below match docker-compose.yml.
+
+# PORT=3000
+
+# DATABASE_HOST=localhost
+# DATABASE_PORT=5432
+# DATABASE_USERNAME=postgres
+# DATABASE_PASSWORD=admin
+# DATABASE_NAME=postgres
+
+# REDIS_HOST=localhost
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
+
+# API keys for LLM feature modules (e.g. @loopstack/claude-module)
+# ANTHROPIC_API_KEY=

package/fixtures/app/nest-cli.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "assets": ["**/*.yaml"],
+    "watchAssets": true
+  }
+}

package/fixtures/app/src/app.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { LoopstackModule } from '@loopstack/loopstack-module';
+import { HelloModule } from './hello/hello.module';
+
+@Module({
+  imports: [LoopstackModule.forRoot(), HelloModule],
+})
+export class AppModule {}

package/fixtures/app/src/hello/hello.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { StudioApp } from '@loopstack/common';
+import { HelloWorkflow } from './hello.workflow';
+
+@StudioApp({
+  title: 'My First App',
+  workflows: [HelloWorkflow],
+})
+@Module({
+  providers: [HelloWorkflow],
+})
+export class HelloModule {}

package/fixtures/app/src/hello/hello.workflow.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+
+const InputSchema = z.object({
+  name: z.string().default('World'),
+});
+
+type InputArgs = z.infer<typeof InputSchema>;
+
+@Workflow({
+  title: 'Hello World',
+  description: 'Greets you by name — replace this with your first real workflow.',
+  schema: InputSchema,
+})
+export class HelloWorkflow extends BaseWorkflow<InputArgs> {
+  @Transition({ from: 'start', to: 'end' })
+  async greet(_state: unknown, ctx: RunContext<InputArgs>) {
+    const greeting = `Hello, ${ctx.args.name}! 👋`;
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: greeting,
+    });
+
+    this.assignResult({ greeting });
+  }
+}

package/fixtures/app/src/main.ts

@@ -0,0 +1,8 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(process.env.PORT ?? 3000);
+}
+void bootstrap();

package/package.json

@@ -1,15 +1,41 @@
 {
   "name": "@loopstack/cli",
-  "version": "0.15.1",
-  "description": "Global wrapper for Loopstack local commands",
+  "displayName": "Loopstack CLI",
+  "description": "Run, trace, and watch Loopstack workflows from the terminal",
+  "version": "0.17.0",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "type": "module",
   "bin": {
-    "loopstack": "./bin/loopstack.js"
+    "loopstack": "dist/main.js"
   },
-  "files": [
-    "bin"
-  ],
-  "keywords": ["loopstack", "cli"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "engines": {
-    "node": ">=16"
-  }
-}
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "watch": "tsc -p tsconfig.build.json --watch"
+  },
+  "dependencies": {
+    "@loopstack/client": "^0.37.1",
+    "@loopstack/contracts": "^0.37.0",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.6"
+  },
+  "files": [
+    "dist",
+    "fixtures"
+  ]
+}

package/bin/loopstack.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-
-const { spawnSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-function findPackageJson() {
-  let dir = process.cwd();
-  const root = path.parse(dir).root;
-
-  while (dir !== root) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-
-  return null;
-}
-
-const projectRoot = findPackageJson();
-
-if (!projectRoot) {
-  console.error('ERROR: No package.json found');
-  process.exit(1);
-}
-
-const result = spawnSync('npm', ['run', 'loopstack', '--', ...process.argv.slice(2)], {
-  cwd: projectRoot,
-  stdio: 'inherit'
-});
-
-process.exit(result.status || 0);